很多 humanoid 项目不是死在算法不够强，而是死在“谁发什么指令、谁回什么状态、什么算完成、出了错怎么回退”没有先定清楚。 这篇文章想解决的就是这个问题：如果你准备把人形机器人接进真实工作流，不管场景是工厂、仓储、巡检还是实验线，都应该先把接口契约、硬件抽象、记录格式和验收回归标准定下来。最关键的工程判断是：先把系统做成“可接入、可观测、可回放、可验收”，再去追求更炫的 demo。
这篇适合谁
- 正在搭 humanoid 软件栈、需要定义模块边界的团队
- 准备把机器人接入 PLC、MES、WMS、调度系统或自建任务平台的人
- 已经能跑通 demo，但每次改版本都怕把旧流程搞坏的工程团队
- 想先把接口、日志、验收体系搭稳，再扩技能库和场景的项目负责人
先纠正几个很常见的误区
- 误区 1：先把本体做强，接口后面再补。 现实里往往相反。接口晚定，后面每接一个系统都要重新改状态机、消息定义和异常回退。
- 误区 2：只要 ROS topic 能通，就算系统打通了。 topic 只是传输，不等于契约。没有明确的任务输入、完成条件、失败码和超时语义，调试成本会不断上升。
- 误区 3：硬件抽象越细越好。 过细会让你在 bring-up 阶段陷进适配泥潭。先把 command/state/read/write 这些稳定边界定住，比一次性抽象所有细节更重要。
- 误区 4：日志能录下来就够了。 真正有价值的是“能不能按同一 schema 回放、对齐版本、复现实验和验收结果”。
关键实现判断
如果你要做人形机器人项目的“标准化”，我建议先定四层，而不是一上来追求大而全的行业标准：
- 任务层契约：任务 ID、目标对象、前置条件、完成条件、失败码、人工接管入口。
- 执行层契约：技能调用输入输出、状态流转、可取消点、超时与重试策略。
- 硬件层契约：关节/执行器/传感器的 command interface 和 state interface 分离，避免控制器和硬件驱动彼此绑死。
- 记录与验收层契约：同一套日志 schema、版本号、时间基准和回放入口，让回归测试能重复跑。
外部工程上可以直接借鉴几种成熟做法：ROS 2 官方接口文档把 topic、service、action 三类通信语义拆得很清楚，适合拿来约束你自己的任务接口；ros2_control 明确区分 command interface 和 state interface，适合作为本体驱动抽象的底线；OPC UA Robotics Companion 更像上层系统对机器人状态、诊断和控制能力的统一描述；MCAP 这类自包含日志格式则适合做跨版本记录、远程分析和失败回放。
分步实践指南
第 1 步，先画“任务闭环”，不要先画总架构图
先挑 1 个最可能落地的任务，比如“从工位 A 抓取料盒并送到缓存位 B”。把下面这几项写成表，而不是留在脑子里：
- 任务输入：目标工位、目标对象、数量、优先级、截止时间
- 前置条件：机器人在线、定位通过、自检通过、夹爪状态正常、目标区域空闲
- 过程状态：接单、导航中、到位确认、抓取准备、执行中、复核中、交付完成、异常等待
- 输出结果：成功、部分成功、失败、需人工接管
- 失败码：目标缺失、定位偏差、抓取失败、关节过流、通信超时、安全区触发
这一步的目的不是“把状态写得漂亮”，而是避免后面出现同一个失败在规划器里叫 A、在运维平台里叫 B、在日志里又叫 C。
第 2 步，把 topic / service / action 各自用在该用的地方
ROS 2 的官方接口设计很值得直接照着用：高频连续状态走 topic，一次性查询或配置走 service，长时执行、需要反馈和取消的技能调用走 action。很多 humanoid 项目最大的问题，是把所有东西都塞进 topic，最后无法定义取消、重试和超时语义。
更稳的做法是：
- topic：关节状态、电池、模式、故障标志、心跳
- service：参数读取、工具标定、配置切换、诊断查询
- action：导航到点、抓取任务、门把手操作、巡检路线执行
只要你的“技能”需要运行 3 秒以上，且中途要反馈进度、允许取消或人工接管，优先把它设计成 action，而不是一个没有生命周期的 topic 命令。
第 3 步，硬件层只承诺稳定边界，不承诺一切细节
ros2_control 的价值不只是“能控关节”，而是它把硬件抽象成了比较清楚的 command/state 边界。对 humanoid 项目来说，这很关键，因为你早期可能同时会碰到：
- 不同代次的执行器驱动板
- 关节编码器、力矩估计、电流采样精度不一致
- 上肢、腿部、手部刷新频率不同
- 真机、仿真、回放三种数据源并存
所以硬件抽象的第一目标不是“统一所有能力”，而是先保证：
- 上层永远清楚哪些是可写命令，哪些是只读状态
- 控制器掉线或升级时，不会破坏底层驱动协议
- 同一控制接口可以切到仿真/假驱动/真机做回归
如果你现在的驱动层还把“发送目标位置”“读取编码器”“清故障”“切模式”全混在一个私有脚本里，这一层就应该先重做。
第 4 步，对外系统接入时，先统一状态和诊断语义
很多人一提标准化，就只盯着控制命令。实际上真实部署里，更先出问题的是状态接不上。上层系统最需要的是：机器人现在是不是可派工、有没有被人工锁定、是否处于安全降级、最近一次失败原因是什么、恢复需要人工还是自动。
这也是 OPC UA Robotics Companion 这类规范有参考价值的地方，它先强调把机器人和运动系统的状态、诊断、上层可读信息描述清楚，再往控制扩展。你不一定要整套照搬，但至少该把以下字段变成稳定契约：
- 运行模式：Auto / Manual / Teleop / Recovery / E-Stop
- 可用性：Available / Busy / Fault / Locked
- 任务状态：Queued / Running / Blocked / Done / Failed / Aborted
- 故障级别：告警、降级、停机
- 恢复建议：自动重试、等待人工确认、要求现场检查
只有这些字段先统一，MES/WMS/调度系统才能真的把机器人当一个可管理资源，而不是一个黑盒 demo。
第 5 步，日志格式先统一，不然后面没有真正的回归
如果同一台机器人上的状态日志、任务日志、视频时间戳和诊断信息分散在四五种格式里，你几乎不可能做高质量失败复盘。MCAP 这类格式值得参考，原因不是“它流行”，而是它支持异构时间序列、自包含 schema、索引读取和中断恢复，很适合机器人项目做多源同步记录。
最低限度建议统一记录：
- 机器人状态流：位姿、关节、电池、模式、故障字
- 任务事件流：接单、状态切换、失败码、人工接管
- 感知关键帧：目标检测结果、追踪 ID、坐标变换版本
- 控制关键量：目标值、实际值、饱和标志、保护触发
- 版本信息：软件版本、模型版本、参数包版本、地图版本
一旦没有版本号，所有“昨天能过、今天不过”的讨论都会变成猜谜。
第 6 步，把验收标准写成能自动跑的回归清单
不要只写“抓取成功率 90%”。那不是验收体系，只是一个愿望。更实用的验收要拆成：
- 接口验收：字段是否齐全，异常码是否稳定，状态是否可解析
- 时序验收：心跳、反馈、超时、取消是否符合预算
- 动作验收：完成时间、重复定位误差、抓取成功率、恢复成功率
- 退化验收：网络抖动、传感器缺失、单个子模块重启后是否仍可恢复
- 运维验收：日志是否完整，故障是否能被远程诊断，是否能定位到责任模块
真正的回归不是“再跑一次 demo”，而是每次改控制器、模型、状态机或参数后，都能重放同一组任务并比较关键指标。
最容易翻车的地方
- 接口字段太自由。 每个模块都能随手加字段，最后没有兼容性承诺，旧工具全坏。
- 状态名字和运维语义脱节。 控制侧说 recoverable fault，现场只想知道“能不能继续派工”。
- 只记录成功路径，不记录失败上下文。 出问题时只剩一句 task failed，根本不够排障。
- 没有版本绑定。 日志里看不出参数包和模型版本，复盘没有可比性。
- 把异常回退藏在人工经验里。 如果恢复流程不写进状态机和接口，项目规模一上来就靠不住。
怎么验证你真的搭对了
- 随机挑 3 个任务，确认上层系统能只靠接口字段判断“是否可派工、执行到哪一步、为什么失败”。
- 断掉一个非关键传感器或制造一次网络抖动，检查状态是否进入约定的降级模式，而不是静默卡死。
- 用同一份日志回放工具重放最近两次失败案例，确认可以定位到是感知、规划、控制还是外部系统问题。
- 替换一层实现，例如把真机驱动切成仿真/假驱动，确认上层控制器和任务层不需要跟着大改。
- 做一次跨版本回归，确认新版本不会破坏旧的字段、失败码和接管流程。
下一步怎么做
如果你还没有标准化基础，不要从写一份很大的“机器人平台规范”开始。更有效的顺序是：
- 先选 1 个真实任务，写任务契约和失败码表
- 再把 1 条 action 链路、1 组硬件接口和 1 套日志 schema 跑通
- 然后补验收脚本和回放流程
- 最后才把这套规范复制到第二个、第三个技能
当你能稳定回答“这次失败是谁的锅、怎么复现、怎么恢复、改完有没有退步”时，项目才算真正从 demo 阶段跨进工程阶段。
延伸阅读与参考来源
- ROS 2 Interfaces: https://docs.ros.org/en/humble/Concepts/Basic/About-Interfaces.html
- ros2_control Hardware Interface Types: https://control.ros.org/rolling/doc/ros2_control/hardware_interface/doc/hardware_interface_types_userdoc.html
- MCAP Introduction: https://mcap.dev/guides
- OPC Foundation Robotics / OPC UA Robotics Companion: https://opcfoundation.org/markets-collaboration/robotics/