2.4 机械臂建模实战复盘：从XML到稳定运行
2.4 机械臂建模实战复盘：从 XML 到稳定运行
本节摘要：前三节的知识点是散装的珠子，本节用一条真实产线把它们串起来：一台六轴桌面机械臂，从 CAD 数据整理、MJCF 骨架搭建、惯量与执行器配置，到第一次仿真自检、问题定位与修复，全程复盘。看别人的完整过程，比自己摸索十次都值——本节的每个翻车点都来自真实项目，每条修复都有可复用的结论。
前一度我们把 MJCF 的结构、树、执行器分别讲完，本节不再引入新概念，而是做一次全程实战：目标是一台能抓取桌上物块的六轴机械臂，交付标准是「加载零警告、悬停不漂移、抓取不穿透」。如果你正要建自己的第一台机器，把本节当模板抄；如果暂时不动手，把它当前三节的综合例题。
从一份报错日志开始
实战的起点不是白纸，而是一次失败的加载。某同事拿到 CAD 组的机械臂数据，兴冲冲写完两百行 MJCF，加载得到一串报错。我们把这串报错当目录用，倒推整个建模流程该怎么做才对——每一条报错背后，都是本节要讲的一个步骤。
XML Error: mesh 'link3_vis' not found line: 47 column: 9 XML Error: body 'wrist' must have mass or inertia line: 88 column: 5 XML Error: actuator 'joint5_motor' ctrlrange must be positive line: 132 column: 11
三行报错分别指向资源路径、惯性缺失、执行器范围三类问题，正好覆盖实战的三个主战场。下面按正确顺序重走一遍，走到哪一步、当初的报错就不会出现，顺手交代清楚。
一、备料：CAD 数据的「翻译」环节
建模的第一个动作不在 XML 里，在 CAD 导出面板上。四件料必须备齐：几何（每个连杆一个网格文件，单位统一成米）、质量表（每个连杆的质量、质心、惯量张量，向结构组要「含内部走线」的真实值）、运动参数表（各关节类型、轴、限位、额定力矩）、驱动方式（这台臂是位置伺服还是力控，决定执行器选型）。
备料的头号坑是单位。某次导出的网格按毫米解析，引擎惯性校验直接拦截——CAD 里那根连杆按米看细得像牙签，惯量算出来小到离谱。修复是在 mesh 标签统一加千分之一的缩放。第二号坑是「视觉与碰撞分离」：CAD 给的网格只做视觉件，碰撞件另用 primitive 手工包一层，圆柱用 capsule、壳体用 box，贴着视觉件外形走。两条纪律守住，后面的路平一半。
图 2-3 六轴机械臂建模复盘：从数据到验收的六站
二、搭骨架：六连杆加夹爪的树
骨架从「最小可运行」生长：先写世界体加地面，加载；加基座（不带关节的焊接体），加载；然后逐节加连杆——每节一个 body、一个 hinge、一个 capsule 碰撞件。逐节加载听起来笨，实际是省时间的聪明办法：报错永远属于刚加的那一节，定位零成本。
各节的 hinge 轴方向按机构图纸填，且要清醒：axis 写在当前 body 的局部系里。这台臂的肩关节绕局部 Y 轴、肘关节也绕局部 Y 轴、腕关节绕局部 X 轴——填错轴的症状很典型：动某个关节时连杆朝不该弯的方向弯。range 从限位表抄，负正顺序不能颠倒，引擎会拒绝倒置区间。夹爪部分用两个 slide 关节对面布置，共用一个 position 执行器经 tendon 耦合——腱把「一根驱动」变成「对称开合」，这正是上一节滑动腱的用武之地。
关键连杆的 inertial 逐杆手填：mass 抄质量表，ipos 填质心偏移，diaginertia 填主惯量。第三行报错的 wrist 正是漏了这一步——纯视觉 body 没有惯性，引擎拒绝让一个「幽灵」参与动力学。
三、接动力与感知：伺服、传感器到位
驱动方式确认是位置伺服，所以六个关节各配一个 position 执行器，kp、kv 从驱动手册抄，forcerange 取额定力矩的八成留安全余量，ctrlrange 与关节 range 对齐。第一版曾把 kp 提到十倍「让跟踪更硬」，悬停测试立刻露馅：末端高频振颤，功率谱里一根刺眼的峰。回调到手册值后振颤消失——伺服增益是物理参数，不是训练超参，这个教训值一回复盘。
感知按任务配：末端法兰贴 site 挂 force 与 torque 传感器，夹爪指腹各贴一个 touch，关节位置速度默认可读。给所有 body、joint、site、sensor 统一命名规范（段号加功能），后面写控制器与日志分析时，按名索引一路畅通。
四、验收：一个自检脚本和三个测试
模型写完不等于建模完成。跑一遍自检脚本，把「数值上可信」变成可断言的事实：
import mujoco import numpy as np model = mujoco.MjModel.from_xml_path("arm6.xml") data = mujoco.MjData(model) # 测试一：悬停。给中立姿态，看末端漂移 mujoco.mj_resetDataKeyframe(model, data, 0) for i in range(2000): # 四秒 mujoco.mj_step(model, data) drift = np.linalg.norm(data.site("tool").xpos - data.key_xpos[0][:3]) print("悬停漂移:", round(drift, 4), "米") # 测试二：抓取。合拢夹爪压住物块，看法向力与穿透 for i in range(1000): data.ctrl[:] = [0, 0, 0, 0, 0, 0, 1.0] # 夹爪指令 mujoco.mj_step(model, data) forces = [data.contact[i].dist for i in range(data.ncon)] print("接触对数:", data.ncon, "最小间距:", round(min(forces), 5))
三项判据对应三类隐患：悬停漂移超标，查增益与重力补偿、怀疑惯量或质心填错；抓取穿透超标，查接触参数与夹爪刚度；接触对数异常（为零或爆多），查碰撞件的 contype 配置。修到三项全绿，这台机械臂才算在试车场拿到了入场券。
变式：换成移动底盘怎么办？骨架站多一个 free 关节的躯干，执行器换成轮子的 velocity，验收标准加一条「直线行驶横向漂移」；换成带平行四连杆的臂？骨架站在相应位置用 equality 的 connect 拼闭环，并接受约束求解的额外开销。流程不变，变的只是各站的具体零件。
本节要点回顾
- 备料定成败：单位制、质量表、驱动方式在动笔前核实，视觉与碰撞几何从一开始就分离；
- 逐节生长：骨架一节一节加、每加必加载，报错定位成本趋近于零；
- 增益是物理量：伺服 kp、kv 抄手册，为训练效果调增益等于给真机埋雷；
- 验收脚本化：悬停、抓取、接触配对三测试写进脚本，模型「稳定运行」要有可断言的标准；
- 流程可迁移：六站流程对底盘、夹爪、闭环机构通用，换的只是零件。
一台通过了验收的样机已经停在试车场门口。它为什么这样动、参数背后引擎在算什么——下一章掀开机盖看动力学。