接口设计：五个节点之间的"契约"怎么签

01问题引入：接口对不上，联调全报废

两个小组并行开发：A 组写语音、B 组写调度。联调那天——

02原理通俗讲解：传菜条的写法与后厨暗号

餐厅的传菜条（接口）怎么写才不出错？三条生活经验直接对应三条设计规律：

03关联知识点：五大系列接口清单

yaml 参数化（config/eai_factory.yaml，/**: ros__parameters: 顶层下发）关键段落：

mode: production            # L7：debug/production 双模式
vision: { tag_id: 3, tag_size: 0.025, tag_family: tag36h11 }   # L56-L63
grasp.tasks:                              # L65-L90 每任务 [x,y,z,pitch] 四元组 + vision 标志
  load:      { vision: true,  observe_pose: [0.16,0.0,0.27,2.5307], place_pose: [0.05675,-0.13166,0.20386,2.93322] }
  sort:      { vision: false, observe_pose: [0.0622,-0.1158,0.1951,3.0371], place_pose: [0.1434,-0.1296,0.2075,2.7283] }
  palletize: { vision: false, observe_pose: [0.145,0.0027,0.1850,3.1381], place_pose: [0.0608,0.1345,0.2051,2.6461] }
safety:  { front_start_deg: -30, front_end_deg: 30, danger_dist: 0.20, persist_time: 0.5 }  # L92-L98
intents:                                   # L110-L117 意图 ↔ 服务名 表驱动映射
  load:      { action: "/eai_factory/start_load" }
  sort:      { action: "/eai_factory/start_sort" }
  palletize: { action: "/eai_factory/start_palletize" }

04实验目标

• 掌握A/C/D/E/F 五系列接口的定义位置、消息类型与方向（谁发布、谁订阅、谁调用）
• 理解"意图 → 任务 → 执行"调用链：intent 话题 → start_load 服务 → grasp/start 服务 → grasp/status 话题 → speak 话题，能画完整闭环
• 掌握config/eai_factory.yaml 参数配置（mode / grasp.tasks / safety / conveyor / intents），会解释意图映射"改 yaml 不改代码"的原理
• 独立完成一份接口清单表（编号/名称/类型/方向/消息/实现位置/行号/一致性），可用 ros2 命令验证（可选）
• 迁移：对任意 ROS2 项目快速产出"接口清单 + 消息类型 + 实现位置"对照表

05实验环境与准备

06动画讲解：从意图到播报的闭环链

跟着光点走一遍完整闭环：虚线 = 话题（异步），实线 = 服务（同步必回执）。注意链路上两处"触发→完成"的两段式：start_load/grasp/start 都是受理即返回，真正完成靠 status 话题回传，最后才经 A2 speak 收口播报。

07互动讲解：接口契约选择台

给一条业务需求，你选哪种接口契约？点击选择查看评审结论：

08实操步骤：阅读、核联、验证三板斧

# ① 五节点的订阅/发布/服务/客户端实现位置（一把抓）
grep -n "create_publisher\|create_subscription\|create_service\|create_client" eai_factory/*.py
# voice_node.py L250-L253: A1 intent / A3 interrupt / A2 speak
# safety_node.py L56-L63:   C1/C2/C3 发布 + C4 客户端
# conveyor_node.py L109-L111: F3 Trigger 服务端
# scheduler_node.py L62-L67:  E1-E3 服务端注册

# ② 运行时验证（可选，需系统已启动）
ros2 node list | grep eai_factory        # 应看到 5 个节点
ros2 topic list | grep eai_factory       # intent/speak/interrupt/danger/...
ros2 service list | grep eai_factory     # start_load/start_sort/start_palletize/grasp/start/...
ros2 interface show std_srvs/srv/Trigger # bool success  +  string message
ros2 interface show geometry_msgs/msg/PoseStamped

# ③ 手动触发装货（须安全环境！Trigger 请求体为空 {}）
ros2 service call /eai_factory/start_load std_srvs/srv/Trigger "{}"
# response: success: True / message: 'load task triggered'

09重点与易错点

• 接口清单表覆盖 A1-A3 / C1-C4 / D1-D7 / E1-E3 / F1-F10，每条含类型/方向/消息/语义/实现行号
• 能默画 语音→intent→start_load→grasp/start→grasp/status→speak 闭环
• 能指出 yaml 五段（mode/grasp.tasks/safety/conveyor/intents）的位置与作用
• 能解释意图映射两种消费方式：voice 读 intent_hints 做提示词（L228）、调度器路由服务（L62-L67）
• （可选）验证记录含 success: True / 'load task triggered' 返回截图或抄录

10实验总结与思考