机器人 Agent
整合与评测 / 第 16 章

毕业项目:桌面搬运助手

在同一场景中搬运两个物体,并应对执行中的变化

现在把前面的几个部件接成一个完整任务:同一台机械臂把红色方块送到蓝色区域,再把绿色方块送到黄色区域;过程中能够应对一次抓空或目标移动,并正确处理重复任务。

两个物体始终存在于同一个 MuJoCo 世界中,由同一台机械臂依次搬运。这样,你既要检查当前任务,也要确认先前完成的结果仍然成立。沿用课程设定:决策由确定性规则驱动,观察来自仿真状态,抓取使用显式附着约束。

本章目标与交付物

完成三个条件下的双物体整理:无扰动、一次抓空、一次目标移动。你需要提交任务定义、事件日志、完成记忆与最终验收;具备渲染环境时,再保存前后图。先通过下面的演示认识整个流程,再自己运行。

观看任务:跟踪红块与绿块各自何时被抓起、运送、放下,留意第一次抓空后的再次尝试。完成两个物体后,系统收到一次重复的红色任务,思考为什么没有再搬运一遍。

本课实验录像
同一场景中的两次搬运与一次重复请求

种子 7,第一次抓空后恢复;红块到蓝区、绿块到黄区,再复核并跳过重复的红块请求。绿色方块部分被机械臂遮挡,最终结果还需对照两物体的验收记录。

本课 SCARA 实际仿真录像 · 状态输入与规则控制 · 无模型调用。动作间加入定格便于读字幕;无音轨。

查看本次动作与验收记录 · 录像生成源码

逐步观看:点击记录跳到对应画面

这段课程录像来自 seed 7、miss-grasp 条件的实际运行,包含 16 次工具调用与一次重复任务跳过。录像帮助你认识动作顺序;后面会用日志解释抓取反馈、任务记忆与最终验收。

先分清主线与扩展实验

毕业任务整合的是下面这条主线。可以先复习自己不熟悉的环节,再继续运行:

已经用于本项目的能力 从哪一章学到 在本项目中的作用
状态、坐标与基础技能 第 2—5 章 读取两个对象,执行移动、抓取与释放
状态反馈与失败恢复 第 6、9 章 检查持物状态,抓空后再次尝试
带证据的任务记忆 第 10 章 保存完成记录,复核重复请求
使用当前目标位置 第 11 章的时效性思想 每轮重新读取目标,避免沿用旧坐标
按条件比较结果 第 15 章 分别验收三种扰动场景

第 12 章主动观察、第 13 章 JSON 解释器、第 14 章学习技能是三项独立扩展练习,当前调度器尚未调用它们;第 11 章的空间缓存类也没有直接装入这里。主线先用精确状态和原有运动技能完成任务,扩展练习告诉你以后可以替换哪些部件。

第一步:先写可验收的任务规格

任务标识 操作对象 目标区域 最终要求
red_to_blue 红色方块 蓝色区域 已释放,并满足位置、高度与速度条件
green_to_yellow 绿色方块 黄色区域 已释放,并满足位置、高度与速度条件

调度队列实际是“红、绿、红”。最后一个红色任务用于检查重复请求处理,不代表场景里还有第三个方块。第一次完成红色任务时保存证据;再次收到它时,先复核红块现在是否仍满足条件,成立才跳过。

一个对象的成功不能代替整个任务成功。最终必须同时满足两个对象的验收。只检查当前活动对象,会出现“最后操作的那个做好了,因此宣布全部完成”的错误。

开始运行前,用三个纸面场景自测:红块完成、绿块未完成;两个都完成;红块曾完成但后来离开蓝区、绿块完成。整体成功应分别是“否、是、否”。第三种情形里,历史可以仍然记着红块曾成功,最终验收仍要以两物体当前状态为准。

第二步:理解系统如何衔接

调度器就是按任务列表决定“接下来做哪一项”的程序;活动对象是这一轮正在处理的红块或绿块。它们与底层控制按下面的顺序配合:

取出任务 → 查完成记忆 → 用当前状态复核
                         ├─ 已完成:跳过
                         └─ 未完成:反馈控制器选择动作
                                      ↓
                           基础技能执行 → 新状态
                                      ↓
                           验收通过后写入完成记忆

调度器决定做谁,反馈控制器决定当前下一步做什么,技能把它变成实际仿真运动,记忆保存已经验收的结果。这样,每一层都能从日志中找到对应证据。

切换活动对象改变的是工具接口查询哪一个对象,并没有重新创建场景。搬运绿色方块时,已经放好的红块仍然存在。若当前任务没有完成,调度器会停止,避免仍持有一个物体时直接开始操作另一个。

记忆也不会代替当前状态。memory.json 中的完成记录表示某个时刻的事实;revalidate_completion 事件说明重复请求到来时又进行了一次检查。如果对象后来离开目标,旧记录应失效,不能继续用“以前成功过”作为理由跳过。

第三步:运行无扰动的完整任务

在已激活环境、包含 lab/ 的目录执行:

python lab/advanced.py capstone --seed 7 --perturb none --out runs/ch16-clean
python -m json.tool runs/ch16-clean/summary.json
python -m json.tool runs/ch16-clean/memory.json

第一次运行先在摘要中找到下面几个字段,其他状态可以随后再读:

{
  "success": true,
  "completed_ids": ["red_to_blue", "green_to_yellow"],
  "skipped_duplicates": 1,
  "tool_calls": 15,
  "model_calls": 0
}

这表示种子 7 的无扰动任务完成了两项搬运,跳过一次重复请求,执行 15 次工具调用。再读 events.jsonl,通过 result.observation.active_object 区分红块与绿块阶段;通过 memory.json 的 events 找到两次 completed 和一次 revalidate_completion。

final_observation.objects.red 与 .green 分别记录两物体的状态。active_object 只是当前查询对象;兼容前面章节的 scene.block_xyz 也只指向当前对象。要判断全部完成,请查看 task.all_success 和摘要的 success,不要只读取 task.success。

按下面三步读第一次运行,避免同时在三个大文件里查找:先在摘要确认“两项完成、跳过一次”;再去记忆文件找到对应的两次完成事件与一次复核;最后才按活动对象阅读技能事件。队列末尾又查询红块,所以最终 active_object 为 red,即使最后一次真正搬运的是绿块。这正是“正在查询谁”与“最后移动过谁”的区别。

第四步:加入一次真实执行中的故障

python lab/advanced.py capstone --seed 7 --perturb miss-grasp --out runs/ch16-miss
python lab/advanced.py capstone --seed 7 --perturb shift-goal --out runs/ch16-shift

抓空条件在第一次满足抓取前置条件时注入失败,反馈控制器重新观察后再次尝试。目标移动条件在首次抓取成功后,将当前目标移到新位置;后续运输需要使用新位置。这两种扰动分别运行,不表示同一回合同时出现全部故障。

发布前 seed 7 的抓空实跑完成了两项任务,执行 16 次工具调用,重复请求跳过 1 次。你需要在自己的日志中找到第一次失败、第二次抓取成功、两个任务完成与重复任务复核的证据,不能仅照抄这个数字。

三个条件的实跑结果可作为核对点。抓空条件比无扰动多一次抓取,其它任务结构不变:

条件 两项任务完成 工具调用 重复请求跳过
none 是 15 1
miss-grasp 是 16 1
shift-goal 是 15 1

目标移动时,既要检查被移动目标对应的物体,又要确认另一个物体最终没有被破坏。这个要求比单物体任务多了一层:某个子任务刚完成,不保证其他已完成条件永远保持成立。

第五步:用独立计算复核两个对象

把下面的程序保存为 check_capstone.py,再运行 python check_capstone.py。同样适用于 PowerShell,不需要 heredoc。它以抓空目录为例,检查其他回合时修改 folder。

import json
import math
from pathlib import Path

folder = Path("runs/ch16-miss")
summary = json.loads((folder / "summary.json").read_text())
memory = json.loads((folder / "memory.json").read_text())
checks = []
for name in ("red", "green"):
    state = summary["final_observation"]["objects"][name]
    distance = math.dist(state["block_xyz"][:2], state["goal_xyz"][:2])
    valid = (
        not state["holding"]
        and distance < 0.045
        and 0.015 < state["block_xyz"][2] < 0.065
        and state["linear_speed_m_s"] < 0.05
    )
    print(name, "水平距离:", distance, "复算成功:", valid)
    assert valid == state["success"]
    checks.append(valid)
assert summary["success"] == all(checks)
assert all(checks), "至少一个对象未完成"
assert set(memory["completed"]) == {"red_to_blue", "green_to_yellow"}
assert summary["skipped_duplicates"] == 1
assert summary["model_calls"] == 0
print("两个对象均通过当前状态验收,完成记忆与重复任务处理一致。")

程序逐对象计算水平距离,然后检查释放、高度和速度。这里 math.dist 计算两点距离,all(checks) 表示两个对象必须同时通过;assert 在条件不成立时停止,便于发现是哪一步不一致。

种子 7 的抓空回合应打印两行“复算成功:True”,水平距离各约 0.0013 和 0.0014 米,最后打印完成提示。它使用仿真器记录的状态复算验收,既不依赖控制器说“完成了”,也不要求从有遮挡的画面猜测结果。

第六步:为自己的运行保存前后图

若第 2 章 doctor 的渲染检查正常,可在新目录运行:

python lab/advanced.py capstone --seed 7 --perturb miss-grasp --render --out runs/ch16-render

这会额外保存 capstone-before.png 与 capstone-after.png,不会录制连续视频。没有可用渲染环境时,先完成不带 --render 的物理与日志实验。

可以对照课程实跑的 运行前图片 与 运行后图片。顶部录像用于观察过程,这两张静态图则方便比较初始布局与最终位置。

最终图中的绿色方块部分被机械臂遮挡。请对照 objects.green 的状态和前面的复算结果判断它是否释放并低速稳定。将视频、静态图和数值记录分别用于过程、布局和验收,就不容易混淆它们能回答的问题。

失败时怎样定位到具体层

没有开始搬运,先检查场景加载与活动对象;到达后抓空,检查技能结果与持物状态;运到旧目标,检查获取位置的时机;跳过了未完成任务,检查记忆是否经过当前状态复核;单个物体成功却整体失败,检查另一个对象。

不要一看到失败就扩大重试次数。不可达目标、错误对象映射和已经过期的任务规格,需要不同处理。当前反馈控制每个子任务有有限动作预算,但没有解决任意障碍、任意移动目标或物体堆叠。

毕业报告与下一次改进

报告包含任务规格、运行命令、种子与版本、三组日志、逐对象验收、恢复事件和已知限制。成功条件应在查看结果前确定;失败回合也必须保留。完成后,用一段话解释系统为什么知道何时继续、何时跳过、何时结束。

可以把这段解释写成三句并自查:①当前任务未完成时,反馈控制器依据当前位置与持物状态选择下一技能;②重复请求有完成凭据且当前验收仍成立时,调度器跳过搬运;③队列处理完后,同时检查红、绿两项状态才报告整体成功。每句至少标出一个实际字段或事件,例如 holding、revalidate_completion.valid_now、task.all_success。能让别人沿着你的三句说明找到原始记录,才算完成这份报告的证据部分。

基础扩展:用新种子重复三个条件,按第 15 章方法报告全部结果。进阶扩展一次选择一条路径:

扩展方向 需要实际接通的地方 新增验收
使用第 12 章视觉 把检测坐标传给动作选择,而不继续读取物体真值 定位误差、遮挡失败与任务完成率
使用第 13 章程序计划 让调度器提交并执行一份计划 分支、节点预算与逐任务结果
使用第 14 章学习技能 加载固定权重,由上层调用到达技能 适用位置范围、到达误差与任务结果

先画出新数据从哪里来、传到哪个接口,再实现和验证。这样,你可以在已完成的主线上增加能力,同时清楚知道哪一条新路径真正工作了。

阅读 SO101 三色积木分拣案例,比较它的视觉与几何控制路径和本项目的精确状态输入;再看 RPent 技能分工案例,思考下一项能力应该放在哪一层。案例是延伸阅读,本课程没有复现其完整机器人与学习模型。

一手参考

本课程实验使用独立的简化教学环境。标为“展厅阅读案例”的录像采用各自的机器人与模型设置;标为“本课实验录像”的内容来自本课程代码的实际运行。
查看本章源文件 · 查看实验说明

学习进度仅保存在当前浏览器。