调酒技能采集 · 操作者指南

这一页是实际录数据时的主要参考。规范全文见仓库 03-software/GOAL-bartender-skill-data-collection.md；这里是操作台前用得上的那部分。

一句话概括这次改变：
不再把行为录成一条很长的「拿起 → 移动 → 放下 → 倾倒」完整轨迹，而是建立可重复调用的技能库：PICK / PLACE / POUR，并区分左右臂。

因为真实的调酒不会每次都「拿起杯子 → 马上放下」。 Pick 和 Place 必须是能被上层单独调用的两个技能。

一、5 个 Task（MVP，只有这 5 个）

句子不能手输，只能在面板上选。选项由 03-software/scripts/bartender_tasks.py 提供 —— 那是唯一事实源，面板、头盔页、录制进程都从它读，三处不会各写一份。

#	Task	canonical 句子（逐字，含句号）	arm mode	这一集什么时候算结束
[1]	右臂 — 拿起杯子 Right Arm — Pick Up Cup	`Pick up the cup with the right arm.`	`arms=1` 右臂	杯子已抓稳、明显离开桌面、手臂稳定持杯。★ 不要在这一集里把杯子放回去 ★
[2]	右臂 — 放下杯子 Right Arm — Place Cup	`Place the cup down with the right arm.`	`arms=1` 右臂	杯子稳放桌面、夹爪已打开并稍微撤离、杯子没有倾倒或滑动。★ 开始时右臂必须已经拿着杯子 ★
[3]	左臂 — 拿起杯子 Left Arm — Pick Up Cup	`Pick up the cup with the left arm.`	`arms=2` 左臂	左臂已稳定拿起杯子。★ 左臂必须有真实示范 ★ 右臂学会不等于左臂学会：两臂在 17 维里占不同维度，旧数据里左臂全程停在 home。
[4]	左臂 — 放下杯子 Left Arm — Place Cup	`Place the cup down with the left arm.`	`arms=2` 左臂	杯子稳放桌面、夹爪已打开并撤离。★ 开始时左臂必须已经拿着杯子 ★
[5]	双臂 — 右倒入左 Bimanual — Pour Right → Left	`Pour from the cup held by the right arm into the cup held by the left arm.`	`arms=0` 双臂	倾倒完成、右臂恢复竖直、双臂稳定。★ 这一集【不包含】Pick ★ 开始时两只手都已经拿着杯子。

为什么句子要锁死。SmolVLA 是语言条件模型 —— 换一句话等于换一个任务。 2026-08-23 实测到的代价：前 31 次实机试验用的是 "Grab the cup"，而数据集里是 "Pick up the cup and place it down"。指令对不上，两天没人发现，因为前 31 次连 task 字段都没存下来。

二、Task 会自动决定 Arm Mode

Task	arm mode	选错会怎样
右臂 Pick / Place	`arms=1`（只右臂跟随）	录出一整批该动的手臂全程不动的数据 —— 看起来正常，训出来什么都不会。所以系统会直接拒绝开录。
左臂 Pick / Place	`arms=2`（只左臂跟随）
双臂倾倒	`arms=0`（两臂都跟随）

这个值在 03-software/configs/teleop_safety.yaml 的 vr_mapping.arms。注意同一个文件顶层还有一个 arms:，那是每条臂的工作区包络，不是模式 —— 别改错了。

三、开录之前的 Checklist

硬件

装的是正确的夹爪
夹爪固定可靠
舵机没有异常（面板上看温度）
要用的那条臂工作正常

工作区

桌面标定有效
workspace limit 有效
物体在安全工作区内
起始状态没有明显超出可达范围

相机

三路相机全部在线
方向正确、没有被遮挡
头部相机在目标位置

Task

Task 选对了
Arm mode 匹配（面板会当场提示）
数据集名正确（选 Task 后自动填）

目标集数 = 50
质量检查 = 开
每 10 集检查一次
出问题暂停 = 开

全部正常才开始第 1 集。

四、录的时候怎么动

改变杯子的位置，不要每次改变抓杯子的基本方法。

	标准动作	主要变化什么
Pick	对齐 → 受控接近 → 闭合 → 抬起 → 稳定 → 结束	杯子位置
Place	已持杯 → 搬运 → 对准 → 下降 → 松开 → 撤离 → 结束	放置目标位置
Pour	两手已持杯 → 靠近 → 调整杯口 → 倾斜 → 倒完 → 恢复竖直 → 稳定	两杯的相对位置

好的多样性 vs 坏的多样性

✅ 好	❌ 坏
杯子位置变了，手臂据此自然调整，抓取策略始终一致	这一集从左边靠近、下一集从上面压、再下一集冲过头再退回来、又一集绕杯子一圈、再一集先撞到再补救

让任务几何发生变化，不要让 demonstration philosophy 每次都变。

五、杯子该放在哪

不要再回到 P1–P5 五个完全固定的坐标点。那会让模型记住几个坐标，而不是根据视觉真正定位杯子。

推荐把主要工作区放在更安全的中间区域，约 120–175 mm，并在这个区域内做连续、小范围的变化。

旧数据同时出现了 Reach Arc、Forward Floor、At The Table Floor 三种 clamp，说明有的位置偏远、有的偏近、下压也偏深。整体 clamp 率约 10% —— 卡在可接受的边界上。 下一批目标 ≤5%。

clamp 类型	说明什么
Reach Arc 高	杯子可能太远
Forward Floor 高	杯子可能太近
At The Table Floor 高	压得太深，或桌面标定有问题

六、什么必须重录

出现下面任何一种，直接 Re-record，不要因为「最后还是成功了」就留下：

没抓到杯子
明显碰撞
走错方向
冲过头
大幅来回修正
抓起后杯子掉落
连续尝试两三次才成功

为什么不能留。留下来等于教模型「大幅补救动作是标准轨迹的一部分」。以后真要学失败恢复，应该单独采 Recovery Dataset。

Re-record 不计入集数，也不会触发质量检查 —— 已在代码里验证。

七、每 10 集自动体检

这件事不再靠你记住。第 10 / 20 / 30 / 40 / 50 集保存完成后自动跑，检查逻辑在录制进程里，面板和头盔只显示结果。

检查项	内容
数据完整性	集数、metadata 可读、parquet 可读、声明帧数 vs 实际行数 vs info.json 三方对账、三路视频文件是否真的在盘上
Clamp 质量	本批 clamp 率 + Reach Arc / Forward Floor / At The Table Floor 分类计数
每集时长	最近 10 集平均 / 最短 / 最长，异常短集告警（2 秒的多半是误触）

clamp 率	判定	会发生什么
≤ 5%	GOOD	继续录
5 – 10%	WARNING	报告，但不打断
> 10%	FAIL	录制自动暂停，等你决定

暂停之后必须你来做决定，面板上两个按钮：继续录（问题不修） 或 停止录制，先修。不做决定它会一直等 —— 这是有意的：静默继续录后面的数据，正是这个闸门要防的事。

闸门不会自动删集、自动改工作区、自动移杯子、自动改轨迹。它只做四件事：检测 → 解释 → 暂停 → 交给你决定。

为什么按「本批」算而不是累计

前 10 集很干净 (1%)，后 10 集很糟 (15%)
累计值 = 8%   -> 判 WARNING，放过去了
本批值 = 15%  -> 判 FAIL，拦下来      ← 现在用的是这个

另外：clamp 日志行是每 2 秒节流打印的，所以数日志行数会严重低估。现在由控制器把 clamp_frames/total_frames 计数器打进日志，闸门用窗口两端做差算真实比率。

八、录制过程中屏幕上一直显示什么

TASK        右臂 — 拿起杯子
LABEL       Pick up the cup with the right arm.
MODE        arms=1（右臂）
DATASET     Suyang99/xlerobot-right-pick-cup-20260823-2130
EPISODE     07 / 50
NEXT CHECK  还有 3 集
QUALITY     GOOD

Task 不会在开始之后消失。头盔里只显示三种提示： 10 / 50 — CHECKING DATA、DATA OK — CONTINUE、 DATA WARNING — CHECK SCREEN。完整诊断在电脑面板上看。

九、第一轮录多少

Skill	集数
Right Pick	50
Right Place	50
Left Pick	50
Left Place	50
Bimanual Pour	50
合计	250

50 是工程 baseline，不是数学上证明足够的数字。正确流程：先录 50 → 训练 → 实机 rollout → 分析失败类型 → 再决定要不要补。 Bimanual Pour 未来很可能需要超过 50，但先用第一批测了再说。

五个 dataset 不等于五个最终模型。分开录是为了干净、好调试；训练时可以把 task-labelled 的数据集合起来做 multi-task training。

十、旧的那 50 集怎么办

Suyang99/xlerobot-cup-grasp-20260820-0230（50 集 / 19453 帧 / 右臂 / task Pick up the cup and place it down）

这批里 Pick 和 Place 连在一条轨迹里，所以不能算作新规范下的 50 条干净 Right Pick 数据。

但它仍然有用：当前云端训练实验、与旧模型对比、验证 batch size / 训练轮数。把它当作 Legacy Combined Pick+Place Dataset —— 不要删除，也不要偷偷改它的 label。

十一、换了夹爪 = 新的 Embodiment Version

夹爪明显变化（更长 / 更软 / 换 TPU / 指尖结构 / 接触面 / 摩擦材料 / Fin-Ray 结构）之后， 相同的关节角已经对应不同的真实接触点。

安装新夹爪 → 机械检查 → 重测桌面/工作区 → 确认新安全区
→ 新建 Dataset Version → 重新录

不要把旧夹爪数据和新夹爪数据无说明地混成一批。

十一·五、Leader-arm 录制：每次 Start 之前的固定流程

问题：按 Start 时跟随臂不会先回 home —— 它只是从当前位置平滑地追向 leader 臂，而写帧从 Start 后第一个 tick 就开始。你手里的 leader 臂如果不在 home，这段「追赶」就被录进了片段开头。它不是任务动作，是两条臂位置不匹配的副产物。

实测（xlerobot-right-pick-cup-20260826-0042，40 集）：开头「还没真正动起来」的帧数 中位 54 帧（1.8 秒），最短 1 帧，最长 111 帧（3.7 秒）。长度每集都不一样，所以按固定帧数后期剪必然剪错。更要紧的是每集第 0 帧的姿态本身就散：肩抬 ±11.4°、肘 ±17.7°、腕 ±19.7°（标准差）。剪掉头解决不了起点不一致 —— 而起点一致才是模仿学习真正在意的。

English — paste this to whoever is at the robot

Before every Start (leader-arm recording page, :8781):

Home → wait until the follower arm has fully stopped.
Move the leader arm (the one you hold) into the starting pose you want — the same pose every time.
Press Adjust twice:
- 1st press: releases the leader's torque so you can pose it.
- 2nd press: saves both arms' current positions as the new home. From now on the follower's home equals the leader's starting pose, so there is no "catch-up" motion at Start.
Then press Start.

Why: at Start the follower does not go home — it eases from wherever it is toward the leader, and recording begins on the very first tick. If the leader is not at home, that easing gets recorded as the awkward head of the clip. Matching home to the leader's pose removes it at the source, and every clip then starts from the same pose — which is also where the arm starts during real policy trials.
Tip: step 3 is needed only once per session (home is saved to disk). After that: Home → put the leader back at that same pose → Start.

为什么这比后期剪更值：试跑时 run_policy_trials.py 不会先把手臂回 home，模型是从手臂当时所在的位置起步的。所以「示范的起点」应该等于「试跑的起点」。在源头对齐，示范分布和推理分布才一致；后期剪只是去掉一段无意义动作，起点该散还是散。

后期剪可不可以：可以，但只在副本上做、剪完过一遍 verify_dataset.py、用新名字上传，训练用过的原始数据集永远不动。lerobot 0.6.2 没有现成的「截头」命令（dataset_tools 只有删集/拆分/合并/改特征/重算统计），按帧范围重写的底层管线是有的，要自己写几十行；而且必须按「动作真正开始」逐集判，不能按固定帧数。

十二、超短版

开录前

1. 选对 Task
2. 确认 Arm Mode 匹配
3. 确认三路相机
4. 确认标定 / 工作区
5. 质量检查 = 每 10 集

录制中

改变物体位置
保持动作策略一致
减少不必要的修正
明显失败直接 Re-record

每 10 集

看：完整性 / 相机 / clamp 率 / 时长
目标：clamp ≤5% GOOD    5–10% 可用但要观察    >10% 暂停处理

核心原则

一个明确的命令 → 一个明确、可重复调用的机器人技能。
而不是：一个命令 → 一整套写死的调酒流程。

本页的 5 个 task 表由 bartender_tasks.py 直接导出，非手抄。规范全文 42 节见仓库 03-software/GOAL-bartender-skill-data-collection.md。