关节能力宣告契约：只做能力探查，不包办动力学求解
系列：人形机器人大脑体系 · 验证工程专项
上一篇《判定不能只靠绿灯》讲的是评测装置怎么上锁。这一篇换到硬件侧：整机厂商拿到我们的「大脑」要接自己的关节，第一个问题永远是——你到底能承诺什么？ 这一篇文章回答它，也回答同样重要的另一半：你不能承诺什么。
目录
一、从一个最常见的对接事故说起 1
二、四类基准：契约宣告的是什么 1
三、拒绝语义：契约里最重要的部分 1
四、实探为准：限位标称值不可信 1
五、桩测试：没有真机也能验对接 1
六、给硬件对接方的四条实操建议 1
一、从一个最常见的对接事故说起
厂商问：「你们的运动控制器能直接给我输出力矩指令吗？」
三种回答：
·「能。」——然后厂商接上去，发现力矩输出受上层策略约束，某些场景下会被安全层截断，对接返工；
·「不能。」——厂商换方案，其实我们底层支持力矩反馈探查，白丢一次合作；
·「我们提供一个能力宣告清单：哪些能力可探查、以什么精度、超限时回执长什么样——你按清单对接，清单之外的部分上层负责。」
第三种是对的。前两种的共同错误是：把「系统里存在某个能力」和「系统对外承诺某个能力」混为一谈。存在不等于承诺——能力可能被上层封装、被安全策略约束、只在特定时序窗口可用。对接出问题，十有八九出在这个混淆上。
所以我们把关节层做成了一份能力宣告契约：它只负责「探查与宣告」，不负责「求解」。
二、四类基准：契约宣告的是什么
整机厂商的关节千差万别：自由度拓扑不同、限位不同、力矩反馈精度不同。契约不可能为每一种硬件写一份专属文档，只能固定四个维度的宣告格式，让所有硬件按同一格式填：
基准维度 宣告内容 对接方拿到后做什么
输入信号模型 各模态信号的类型、通道标识、采样形态 按通道标识送数，不需要猜格式
控制指令模型 指令字段、回执结构、拒绝语义 发指令、对回执、处理拒绝
坐标系 全身关节与传感器的坐标定义与正方向 标定自己的硬件到统一坐标
时序约束 帧率、超时、抖动容忍窗口 校验自己的控制环是否达标
注意每一行宣告的都是「格式与边界」，不是「数值结果」。这不是文档写作风格问题，是职责划分：
能力宣告层回答「我能查什么、精度多少、超限怎么办」；动力学怎么解、轨迹怎么规划、策略怎么选——是上层的事。宣告层一旦替上层求解，两层都会失去可测试性。
三、拒绝语义：契约里最重要的部分
其实超限之后，还有一个最容易漏掉的宣告：指令被拒时，回执长什么样。
很多对接协议只定义了「成功」的回执格式，拒绝时返回一个错误码了事。我们的契约要求拒绝回执与成功回执同构：同样的字段结构，只是结论字段不同，并携带被拒原因（超限 / 超时 / 状态不允许）与当时的关键状态值。
为什么这么坚持？因为对接调试现场，最常见的死法是「发了指令没反应」——不知道是被拒了、丢了还是没收到。同构回执让「被拒」变成一个可读的事实而不是一个超时谜题。这也是我们安全线一贯的原则在对接层的投影：拒绝必须响亮，静默是最贵的失败。
四、实探为准：限位标称值不可信
这里有一个我们真实踩过的坑，值得单独一节。
每个关节都有标称限位——URDF 里写的、厂商手册里印的。但样机实测探查时，个别关节的实际可动范围与标称值差了两度左右。机械装配公差、减速器背隙、限位开关安装偏差，都会造成这种漂移。
问题来了：契约里写标称值还是实探值？
实探为准，标称只作参考。 能力宣告契约里的限位，来自上电后的实探流程（缓慢逼近限位开关触发点，取实测值），并在宣告数据里带上来源标记——这个值是实探的还是标称的，下游可见。
由此派生一条对接纪律：实探结果与标称值偏差超过阈值时，不静默取实探值，而是作为异常上报——因为限位漂移可能意味着机械问题，被契约静默吃掉就浪费了一次免费的健康检查。又是一次同一个教训：差异被「自动兼容」掉的那天，就是它本该报警的那天。
五、桩测试：没有真机也能验对接
硬件厂商常问的第二个问题：「你们怎么保证对接文档和实际行为一致？」
答案是一套桩测试方案。在没有任何真实关节的情况下，用桩替身模拟关节的全部对外行为——按四类基准逐项应答，包括限位探查的返回、力矩反馈的采样时序、超限指令的拒绝回执。
桩测试的价值不在「验证桩」，在验证宣告契约本身：

1. 对接代码先过桩，四类基准逐项核对——文档写的能力，桩必须能逐条演出来；
2. 负向样本必须能演——超限指令必须被拒、拒绝回执必须同构、时序违规必须有可观察的反馈。只演成功路径的桩是装饰品；
3. 桩与真机切换用同一套对接代码——桩上通了，上真机只允许出现「时序类」差异，出现「结构类」差异（多了字段、回执变形）即判定契约与实现脱节。
   第 3 条是关键纪律：桩与真机的差异类型必须分类管理。时序差异（真机抖动、帧率波动）是物理世界给的，对接代码要容忍；结构差异（回执多了字段、拒绝语义变了）是契约与实现脱节，必须修实现或修契约，而不是让对接代码「顺手兼容」。
   六、给硬件对接方的四条实操建议
   把这层契约的使用方式收拢成四条，对接时照着走能避开大部分返工：
4. 对接前先要能力宣告清单，不要先问「能不能」——清单之外的能力，就算底层存在也不在承诺范围内；
5. 限位用实探值，偏差超阈值当作事件处理——不要把自动兼容当成免费的鲁棒性；
6. 拒绝回执按成功回执的同构处理——「没反应」不是一种回执，先查是不是被拒了；
7. 桩测通过只代表结构对齐，上真机后结构差异零容忍、时序差异分类容忍——两类差异混着处理，返工就是这么来的。
   下一篇讲交付侧：《数十个动态库收拢精简：增量 Overlay 打包，守住基线资产不丢失》——几十个零散动态库怎么合、版本迭代怎么保证不丢文件、交付包怎么做到「收到的就是发布的」。
   系列文章：《急停优先：安全链路为什么必须独立于智能决策主线》｜《人形机器人三级牺牲通行体系》｜《长稳测试 12h 金标准：C2/C5 互斥与沙箱回收踩坑》｜《PSSAC 契约：让运动规划读懂台阶、电梯的边界》｜《判定不能只靠绿灯：变异测试+全量自证，我们怎么给评测门禁上锁》｜本文