2. 比赛问题清单与解决方案

这份清单把问题分成“现象、真正原因、处理方式、验证边界”四列。这样做的目的，是避免把一次偶然跑通当成稳定方案。

2.1 任务理解问题

现象：一直在找垃圾，但场景是坑、平台和箱子

原因：当前工作加载的是 Task D。Task D 的评分核心是跨越障碍和推箱，不是识别、抓取和投放垃圾。

解决：先记录 task ID、机器人 ID、动作维度和评分事件，再决定看哪一套代码。Task B 才进入垃圾目标、垃圾桶和投放流程。

验证边界：只看到箱子不能证明整个 Task D 已经完成，还要检查 x 位置、过坑、上平台、终点和评分增量。

2.2 视角和“什么都看不到”问题

现象：viewer 是黑的，或者画面中没有机器人和目标

原因：常见原因不是环境没有内容，而是 headless、viewer 相机位置错误、相机没有启用、机器人位置远离相机，或者启动的是只输出日志的训练入口。

解决：

text先用单环境播放
再打开 cameras / viewer
再保存一帧 RGB-D
再用全局 viewer 检查场景
最后才看 policy 行为

对于正式提交，调试用全局视角和 policy 允许使用的相机要分开。全局视角适合回答“目标是否生成”，不能自动证明它被允许作为策略输入。

2.3 评分问题

现象：机器人动了，但分数只有 2.0

原因：动作执行和评分事件不是一回事。Task D 的低分可能只说明机器人跨过了第一个 x 阈值，尚未完成推箱、平台或终点阶段。

解决：每次 rollout 同时保存：

current_score 时间序列；
机器人 root pose；
箱体位置和相对距离；
阶段状态；
失败时最后 5 秒视频。

不能只看“机器人有没有走”，要看分数在哪个事件之后增长，下一次事件为什么没有触发。

2.4 观测维度和动作维度问题

现象：policy 能训练，但提交时 shape error 或机器人动作异常

原因：训练 policy 的输出维度、官方提交接口的动作维度和机器人构型不一致。B2Piper 和 B2wPiper 不能混用；16D locomotion action 也不能直接当 24D official action。

解决：在部署边界加显式 adapter，并在进入仿真前做 shape 检查：

pythonassert action16.shape[-1] == 16
action24 = adapt_taskd_16d_to_official(action16)
assert action24.shape[-1] == 24

小型参考实现见 code/taskd_reference_adapter.py。它只说明接口和阶段逻辑，不声称已经替代完整 policy。

2.5 推箱接触问题

现象：机器人走到箱子附近，但箱子被顶偏、丢失或卡住

原因：只给一个前进速度命令，无法处理偏航、接触面变化、坑边速度衰减和箱体离开 LiDAR 视野。

解决：将 Task D 拆成显式状态：

textapproach_box
push_box
nav_platform
climb_finish
recover

每个阶段使用不同的速度上限、航向锁定、箱体距离阈值和退出条件。LiDAR 用于估计箱体 bearing/distance；得分用于确认阶段是否真的完成；stuck recovery 用于在分数长时间不增长时后退、转向或侧移。

2.6 训练问题

现象：训练 reward 上升，但官方分数没有上升

原因：训练 reward 可能只奖励速度跟踪、姿态稳定或短期接触，没有覆盖官方评分事件。训练曲线不能替代任务成功率和视频。

解决：建立三层评估：

单元级：观测 shape、动作 adapter、模型加载；
rollout 级：单环境播放、阶段切换、视频和 score trace；
benchmark 级：固定 seed、多次运行、官方评分器或等价本地评分。

每次只改一个变量，保留最好 checkpoint 和对应视频。不要因为新 checkpoint 的训练 loss 更低，就自动覆盖已知可提交版本。

2.7 公开方案迁移问题

现象：把另一个仓库的 `solution.py` 复制过来后，程序能启动但行为不对

原因：公开仓库可能使用不同机器人、不同环境注册名、不同 action scale、不同相机外参和不同评分器。代码能 import 只说明语法和依赖基本可用，不说明控制语义一致。

解决：按下面顺序迁移：

text许可证和上游 commit
  -> 任务/机器人/动作维度
  -> observation key 和归一化
  -> action scale 和关节顺序
  -> 环境注册与 checkpoint
  -> 单元测试和 smoke rollout
  -> 多次评分比较

2.8 Task B 感知与操作脱节问题

现象：YOLO 能识别垃圾，但机器人不会捡或投放

原因：感知模块只提供类别、bbox、深度和世界坐标；它没有自动产生合法的底盘轨迹、末端位姿、夹爪状态机和投放确认。

解决：把感知输出固定成明确接口，再由操作层消费：

textperception_output
  -> target / objects_remaining / obstacles / bin / robot
  -> approach controller
  -> grasp controller
  -> carry controller
  -> release verifier

yma867 的感知 README 是接口参考，但其 solution.py 明确是 zero-action placeholder，因此不能把视觉测试通过误认为垃圾收集完成。

2.9 发布问题

现象：想把全部训练目录和外部仓库直接提交 GitHub

原因：训练目录通常包含 checkpoint、缓存、视频、仿真资产、日志、私有路径和 token。直接提交会导致仓库膨胀，也可能泄露凭据或违反第三方分发边界。

解决：

GitHub：教程、轻量源码、配置模板、问题复盘、许可证和固定版本链接；
Hugging Face：模型权重、过滤后的数据、完整源码快照、日志归档和 SHA256；
本地或服务器：Isaac Sim、conda 环境、缓存和未经清理的中间产物。

2.10 验证记录模板

每一次正式记录至少包含：

text任务 / 机器人 / 环境 ID
代码 commit
checkpoint SHA256
观测维度 / 动作维度
GPU 与 Isaac Lab 版本
num_envs / seed / iteration
score trace
视频路径
成功阶段
失败阶段与下一步改动