机器人 demo 只有在整次运行可检查时才可信

Core Claim

小型自动驾驶汽车演示很容易看起来比实际更完整。车在轨道上绕行，路上有几个障碍物，终端打印 ROS 2 节点日志，截图显示 Webots 世界正在运行。问题在演示结束后才真正开始：另一个人能不能重建这个 world，启动 simulation，看到相同 sensor topics，理解 controller，知道部署卡在了哪一层？

这才是机器人项目里真正的工程问题。可见的车只是最后一层。下面还有 world model、sensor definition、controller timing、topic connection、launch path、graphics dependency、container boundary 和 documentation。如果这些层不可检查，演示就更像一段视频，而不是一个系统。

CSE434 机器人项目的价值正在这里。它是一个 Webots + ROS 2 Jazzy 的自动驾驶小车仿真交付物，包含道路回路、静态障碍物、Ackermann-like vehicle、camera、LiDAR、GPS、IMU、path following、obstacle avoidance，以及面向 HPCC 环境的 headless deployment 说明。它最强的公开主张不是“已经完成了完整验证的集群部署”，而是更窄、更诚实的一句话：这个课程级机器人演示被拆成了可检查的工程层，world、sensor、controller、launch file、deployment plan 和 blocker 都可以被读出来。

这个区别很重要。一个可靠的机器人交付物应该让成功和不完整都可见。

演示真正容易失败的地方

机器人项目常常在无聊的地方失败。controller 在数学上可能合理，但 simulator 在远程机器上起不来。world 在本地能加载，但 container 缺少图形依赖。path follower 可以发布 velocity command，却没有 bridge 把命令转进模拟车辆。LiDAR avoider 在合成 scan 上逻辑正确，但 simulator 从未发布 /scan。最终视频可能把这些差异都遮住，除非项目把实际工作的层记录下来。

这个项目围绕正确的层组织：Webots 提供仿真物理环境；ROS 2 提供节点结构和消息传递；一个 controller 负责沿预定义 circuit 跟踪路径；另一个 controller 在 LiDAR sector 指示近距离障碍物时改写导航命令；Webots bridge 发布 sensor data 并消费 velocity command；单独的 launch path 区分普通 simulator run 和 headless run。

关键细节是，这些层不只是被散文描述，而是作为独立实现表面存在。path follower 可以和 obstacle avoider 分开读；world 可以不依赖 ROS package 先检查；deployment notes 记录了已完成部分和 HPCC container 未解决部分。这就是“这是一个视频”和“这是一个系统状态”之间的差别。

world、sensor 和 controller 必须合在一起看

机器人 simulator 不只是视觉舞台。world file 定义了 controller 会继承的物理假设。在这个项目里，world 是一条大约 50 米 x 50 米的封闭道路赛道，包含 lane markings 和五个静态障碍物，例如 box、cone、cylinder，被放置在赛道不同位置。车辆从赛道下方附近开始，sensor stack 明确：360 度 LiDAR 有 360 个水平读数和 10 米范围，camera 是 640 x 480、60 度视场，GPS 用于定位，IMU 用于 heading。

这些细节会改变 controller 的意义。当 world 是已知 circuit、path 是预定义时，pure pursuit path follower 是合理且可解释的选择。对开放世界自动驾驶来说，这当然不能支撑强 claim；但对课程仿真器来说，它是一个合适 baseline，目标是把 sensor feedback、state estimate、path tracking、obstacle reaction 和 launch mechanism 连到一个可检查系统里。

obstacle avoidance 也是同样逻辑。实现是 reactive layer，不是完整 planner。它把 LiDAR readings 分成 sector，检查前方和前侧区域的近距离障碍物，并调整 velocity command。障碍物太近时，emergency threshold 让车辆停止；中等距离触发左右避让；更远的阈值让车辆减速，同时保留基础导航意图。这种行为是有意做得直接的：读者能把每个 branch 映射到 sensor condition 和 command output。

因此，“可复现机器人项目”不只是安装依赖。可复现还意味着读者能理解实验契约：正在模拟什么世界，机器人能感知什么，controller 读取什么状态，发出什么命令，launch path 预计会在哪里失败。

path following 的价值在于简单可调

path follower 使用 pure pursuit controller，在默认 15 个 waypoint 的循环路径上运行。它订阅 odometry，可以选择接收替换路径，并以 10 Hz 发布 velocity command。默认参数有意保持小而可读：2.0 米 lookahead distance、2.0 米每秒 target speed、1.0 rad/s maximum angular velocity，以及 waypoint tolerance。

这里没有神秘模型，这反而是优点。当小车错过 waypoint、转弯过度或振荡时，可能的 knob 是可见的：lookahead distance、target speed、tolerance、maximum angular velocity、waypoint spacing 或 odometry quality。controller 没有躲在 learned behavior 或复杂 planner 后面，而是给项目提供了一个能在 simulator 里调试的解释性 baseline。

pure pursuit 也创造了有用的复现测试。如果 world 和 odometry 接好了，path follower 应该发出把车引向下一个 waypoint 的 command message。如果没有，就可以分离问题：没有 odometry，坐标系错了，初始姿态错了，waypoint sequence 错了，command 没有 subscriber，或者 simulator bridge 被卡住。当这些检查成为可能，演示就更可信。

LiDAR 避障是优先级层，不是完整规划器

obstacle avoider 也很直接。它监听 navigation command 和 LiDAR scan，然后发布最终进入车辆的 command。如果 avoider 被禁用，它直接透传导航命令；如果障碍物非常近，它发出 stop；如果前方 sector 被阻塞，它根据左右哪边有更多空间选择转向；如果两侧都被阻塞，它在转向时后退；如果障碍物靠近但还没进入硬避让区，它降低速度。

这不是 Dynamic Window Approach，不是全局 re-planning，不是 SLAM，也不是 semantic perception。它是一个 reactive safety layer。这个边界必须写清楚，因为更大的 robotics architecture 很容易让人以为项目包含 lane detection、EKF-like state estimation、DWA local planner、cost map 或正式 measurement validation。对更完整的系统来说，那些都是合理方向，但被检查的实现只支持一个更简单的主张：Webots world 上的 path following，加 LiDAR sector obstacle reaction。

简单主张仍然有价值。它展示的是一个主要工程模式：当近距离障碍物出现时，导航命令不能永远是最终权威。第二个节点可以拦截或改写 command stream。即使生产版使用更先进的 local planner，这种 command priority pattern 也会在真实机器人系统中反复出现。这里的价值是 override 逻辑可读、可检查。

Webots bridge 是关键运行时界面

这个项目里有两种“车辆 driver”概念。一种是独立 ROS 2 vehicle driver interface，它公开 sensor publisher 的形状，但 wheel-setting 方法更像接口 stub。另一种更关键，是实际 Webots runtime path：初始化 Webots controller bridge device，启用 LiDAR、camera、GPS 和 IMU，发布 ROS 2 sensor messages，订阅 velocity command，并在 simulation loop 中更新 Webots wheel motor speed。

这个区别很重要，因为公开交付物不能让读者推断超出代码支持的内容。如果独立 driver 是唯一证据，项目就会弱很多。bridge file 给出了具体 integration path：Webots device 成为 ROS topics，ROS velocity command 成为 motor update。

剩下的问题是这条完整 bridge path 是否在目标环境中跑通。项目 deployment notes 没有声称完成了 HPCC Webots demo。它记录的是 ROS 2 package 已经 build，主要节点可用，而 Webots container 仍然受 Docker、Singularity build permission、remote builder authentication 和 GUI-related libraries 缺失等 HPCC 限制影响。这就是正确的证据边界。

headless 部署让 demo 接触真实环境

本地 simulator demo 是宽容的。笔记本电脑可能已经有 display server、缓存好的包、合适的 graphics driver，以及知道该看哪个 terminal 的作者。HPCC deployment 会去掉很多这种舒适感。simulator 必须在没有 GUI 的 container 或远程环境里运行，需要 software rendering 或仔细配置的 GPU access。launch path 必须 source ROS 2，找到安装后的 workspace，找到 world，以 headless mode 启动 Webots，并启动兼容 simulation time 的 ROS nodes。

CSE434 项目尝试了这个边界。它包含 headless launch path：启动 Webots，运行 path follower，运行 obstacle avoider，并在最终 velocity topic 之前让 avoider 接入 path follower command。它也包含打包 Webots 的 Docker 和 Singularity 材料。

部署说明比完美 claim 更重要。它记录 HPCC 环境没有直接 Docker、用户没有配置 Docker 组、Singularity fakeroot/build permission 不足、remote builder authentication 失败、Webots 缺少 GUI libraries。换句话说，项目展示了 headless Webots + ROS 2 所需的系统组织，但没有提供足够证据声称完整 HPCC Webots simulation 已经端到端跑通。

这不是扣分点，而是诚实边界。真正有用的工程报告不会把 blocker 擦掉。它会告诉读者：哪些层已经存在，哪些层已经 build，哪些层有接口，哪些层仍然需要运行证据。

当前证据支持的四个结果

第一，仿真交付物结构完整到足以检查。world 定义了道路 circuit、obstacles、robot body、four wheels 和 named sensors；ROS package 定义了 vehicle driver、path follower 和 obstacle avoider 的 executable entries；Webots bridge 把 simulator devices 接到 ROS topics 和 velocity command；launch files 描述普通入口和 headless 入口。

第二，导航逻辑在算法层是真实实现，不是占位文案。path follower 对 waypoints 和 odometry 做 pure pursuit 计算。obstacle avoider 实现基于 LiDAR sector 的 reactive handling，包含 emergency stop、turn choice、slowdown 和 pass-through modes。这些算法很克制，但它们不是空壳。

第三，文档解释了别人如何尝试复现。它描述 container setup、workspace build、topic monitoring、manual velocity commands、parameter tuning、troubleshooting、SLURM-style resource allocation，以及在完整 simulator 未解决前用 synthetic odometry 或 scan 做替代演示路径。机器人复现经常失败在“下一步我要输入什么”这一层，所以这些说明本身有价值。

第四，项目如实记录了 deployment boundary。ROS 2 workspace 被记录为已 build、可测试；完整 Webots container path 仍然 blocked。公开结论应该是“实现和复现计划存在，HPCC headless Webots run 仍缺最终运行证据”，而不是“已经验证完整集群部署”。

对一篇可信技术作品集来说，这已经足够。前提是 claim 必须和证据匹配。

这个项目没有证明什么

它没有证明自动驾驶性能。已检查材料中没有 success rate、lap completion time、path error curve、collision count 或 repeated trials。它不应该被写成 benchmark。

它没有证明一个强 production robotics stack。没有 confirmed SLAM，没有 perception model，没有 global planner，没有 uncertainty-aware state estimator，没有正式 controller verification，也没有 hardware deployment。camera 作为 sensor 存在，但检查到的 controller logic 不依赖视觉。

它也没有证明 HPCC 已经完整部署。deployment notes 记录的是 Webots container path 被环境限制卡住，demo pending。这个 blocker 是交付物真相的一部分。

另外，文档目标和代码证据之间有一些需要谨慎表达的差异。独立 vehicle driver file 包含 wheel-setting stub，更强的 runtime 证据是 Webots bridge，它直接更新 motor。细心读者应该把独立 driver 看作接口草图，而不是主要 drive proof。

最后，视觉故事要和代码故事一样严格。概念架构图可以帮助理解，但不能暗示每个 planning、estimation 或评测 box 都已经实现。这个项目最强的视觉边界更窄：Webots world、ROS 2 bridge、odometry / LiDAR / camera / GPS / IMU topics、pure pursuit、LiDAR sector avoider，以及 HPCC/container blocker。

工程教训

这个项目最好的教训不是“我造了一辆自动驾驶车”。更具体地说：当每个重要层都可检查，并且每个未解决层都被命名时，机器人演示才会变得可信。

这个教训超出 robotics。智能体系统、法律自动化、仿真工具和数据 pipeline 都有类似 failure mode。当环境脆弱时，表面输出很容易显得完整。唯一更持久的答案是公开 runtime contract：input、state、controller 或 policy、output、launch path、verification method 和 blocker。

对 Webots + ROS 2 来说，这个 contract 是：

world 定义任务；sensor 定义机器人能知道什么；bridge 定义 simulator state 是否成为 ROS message；controller 定义 state 如何变成 action；launch path 定义系统能否离开作者机器启动；deployment notes 定义哪些进入了实际运行，哪些还没有。

一旦这些部分可见，即使是不完整 demo 也有用。读者能看到什么值得信任，什么需要重跑，什么需要调参，什么还需要完成。这比一个没有复现痕迹的干净视频更诚实。

下一步应该补证据，而不是先加新功能

下一次迭代应该优先补 evidence。

第一，补一份 clean run log。它应该来自预期 headless path，包含 simulator start、node start、topic list、active sensor topics、command flow 和 termination status。如果仍然失败，也应该能清楚识别 blocker 层。

第二，补不依赖完整 simulator 的小型可重复测试。path follower 可以用 controlled odometry updates 测；obstacle avoider 可以用 synthetic LiDAR scans 测 front clear、front blocked、emergency stop 和 both sides blocked。这些测试会让 controller 行为在 Webots container 解决之前就更可信。

第三，补和代码匹配的视觉证据。短 GIF 或截图序列应该显示实际 Webots world 和 ROS topics，而不是更宽泛的概念 stack。如果图仍然是概念图，就应该标注为 concept，并保持在实现范围内。

第四，继续解决 container path。部署说明已经列出可行路线：local Docker build 转移到 HPCC、X11 development node、Sylabs remote builder，或 HPCC 对 fakeroot / prebuilt Webots image 的支持。跑通其中一条路径，会把交付物从组织良好的部分演示推进到更强的可复现 simulation。

这些改进都不需要扩大 claim。它们会让现有主张更容易被验证。

为什么这篇要诚实写边界

CSE434 项目的公开价值不在于把课程项目包装成完整自动驾驶系统，而在于展示工程判断：可以把一个机器人 demo 拆成 world、sensor、bridge、controller、launch、deployment 和 blocker；可以说清楚每层的状态；可以承认还没有端到端跑通的地方。

这类诚实边界对作品集很重要。强项目可以用结果说话，弱证据项目必须用边界说话。如果边界写得清楚，它仍然能证明工程能力：知道怎么组织系统，知道怎么让别人检查，知道什么不能被 claim。

对我后来的工作来说，这个经验也很直接。无论是法律智能体、评测 harness，还是生成系统，最危险的不是失败本身，而是失败层不可见。一个可检查的系统即使没完成，也比一个只展示成功画面的系统更有学习价值。

参考材料

1. GitHub: https://github.com/ZiAngGu1/CSE434-honors-option
2. CSE434-honors-option README and DEPLOYMENT_STATUS.