机器人实操复现记录：用溯源模型与数据集目录规范整理步骤、输入和责任人

在机器人培训路径里，很多学习者卡在“做得出一次、写不清第二次”。启动节点、订阅话题、跑通演示都不难，难的是把一次实操变成别人能照着重做、能追责、能查例外的记录。本文不给空泛方法论，而是给出一套可落地的记录结构：把每一次操作拆成步骤、输入、观察、例外和责任人，并用两套公开规范作为证据骨架——PROV Model Primer帮助我们把“谁在什么时候用哪个实体做了什么活动”表达清楚，Data Catalog Vocabulary (DCAT) Version 3帮助我们给数据集、分发版本和目录关系建立可检索的描述。下面的六个部分按实操顺序展开，可直接抄进你的实验记录本。

一、先定“实体”：把被操作对象从命令行里拎出来

PROV 把世界里的东西叫 entity（实体），活动影响或生成它们。机器人实操中最容易漏记的就是“输入到底是什么实体”。你敲下 ros2 launch 时，真正被使用的实体不只是启动文件，还包括参数 YAML、URDF 模型路径、标定文件、地图文件，以及某个已经被录制的 bag 数据。记录时不要写“跑了导航”，而要写：输入实体列表——启动文件 nav_bringup/launch/nav.launch.py、参数文件 params/nav2_params.yaml（修订号 r17）、地图 maps/office_1024.yaml。每个实体给一个本地标识和存放位置，就像 PROV 要求区分“同一个东西的不同呈现”。如果 bag 来自他人，还要写来源目录；这正好对应 /type/14.html 中涉及的数据来源与类型区分场景。

二、再写“活动”：每一步都写成可复现的动作行

PROV 的 activity（活动）是发生在一段时间内、使用或生成实体的过程。我们的实操记录要把活动写成一行行可复现命令与时间窗。例如：09:12–09:15，执行“加载地图服务器”，命令 ros2 run nav2_map_server map_server --ros-args -p yaml_filename:=maps/office_1024.yaml；09:16–09:18，执行“启动定位节点”，命令 ros2 launch nav2_bringup localization_launch.py。每条活动行后面接“使用实体”字段，引用第一部分编号的实体。这样别人重做时，不是靠记忆，而是靠活动—实体使用关系。要注意把“等待”也写成活动：比如 09:18–09:19 观察 TF 树稳定，不是空白时间，而是带观察目标的活动。若你在做录制与回放，可参考 /type/25.html 中关于运行日志与录制数据的边界处理。

三、输入与观察：把命令行回显变成结构化字段

机器人培训中的“输入”容易被理解成只指你敲进去的东西；但在可复现记录里，输入包含命令、参数值、环境版本和上游实体。观察则是执行后你实际看到的系统状态：终端输出片段、ros2 topic list 的返回、tf2_echo 的数值、RViz 中某个坐标系是否出现在期望位置。我们建议每个活动下固定两个子块：“输入”写命令与参数原值，“观察”写回显摘要。不要粘贴全部日志，而是摘取关键行，例如“出现 [map_server]: Loading map from YAML 且无 error”。如果某次观察依赖特定命名空间，要在输入里写清 --ros-args -r __ns:=/robot1，避免下次在默认空间里找不到话题——这正是 /type/17.html 讲到的命名空间和重映射核对问题。

四、例外记录：不是失败才写，而是分叉都写

可复现步骤最难的是例外。PROV 允许表达 revision（修订）与 derivation（派生），对应到实操就是：同一活动在不同输入下走了不同分支。比如地图加载活动，正常观察是地图尺寸 1024×1024；例外 A 是 YAML 里 resolution 写成 0.05 但图片是 0.025，导致 RViz 显示偏移，此时记录“例外：参数与图像元数据不一致，回退到上一版 YAML r16 重跑”。例外不要只写“失败了”，而写触发条件、系统表现、你的处置动作、责任人确认时间。另一个常见例外是 bag 回放时时钟源没切到 sim time，表现为 TF 超时；要在例外块里写“观察：odom→base_link 超 0.2s 未更新；处置：设置 use_sim_time:=true 并重放”。把这些分支编号，后续查询时能直接跳到对应处置路径。

五、责任人与代理：用 PROV 的 agent 字段固定到人

PROV 用 agent（代理）表示对活动负有责任的人、组织或软件。机器人小组实操常出现“大家都在终端前，出事找不到人”。记录模板里必须有“责任人”字段：执行命令的人、复核观察的人、批准参数变更的人，可以是不同人。格式如：操作者 学员A（09:12 活动执行）；复核者 导师B（09:19 观察签字）；参数变更批准者 组长C（r17 参数替换）。如果是脚本自动生成活动，agent 也可以是 CI 任务名，但必须同时写人类复核者。责任人记录方法很简单：每个活动行末尾加 agent:执行人/复核人，例外处置再加处置人与时间戳。这样当后续要判断某条记录是否可信任时，依据就是责任链而不是印象。

六、用 DCAT 给数据集和目录做外壳描述

当你的实操不止一次、而是一批 bag、参数版本、地图修订形成小数据集时，需要目录级描述。DCAT 3 是 W3C 的推荐标准，用于在网络上发布数据目录、描述 dataset 与 data service，并支持版本、数据集系列等属性。我们可以借它的思路：把一次培训产生的数据集登记为 catalog entry——标题、标识符、生成它的活动编号、责任人、分发文件（distribution）及校验方式、上一版本链接。比如“office_1024 地图修订集”作为一个 dataset，包含 r16 与 r17 两个 version，r17 用 previousVersion 指向 r16；它的 distribution 是实际 YAML 与 pgm 文件，可附摘要值。这样多个机器人、多个场地产生的结果能在同一目录结构里被检索，而不是散落在个人电脑的 ~/Downloads 里。将 DCAT 的目录外壳与 PROV 的活动溯源结合，你得到的不是孤零零的命令历史，而是一份“谁、用哪份数据、按哪步、产生了哪个可分发结果”的完整证据网，也正好支撑本站机器人培训路径中从单次实操走向可复用资产的目标。