Hands On High Ceiling

手把手 7：工程化组合示例

本课把前几课的单状态示例升级成可独立部署的客户动作包。

推荐目录

/opt/bxi/mods/com.customer.motion_pack/
  mod.yaml
  plugin.py
  walk_state.py
  gesture_state.py
  transitions.py
  assets/
    locomotion.onnx
    gesture.npz
    gesture.onnx

系统 YAML 只追加根：

mod_paths:
  - /opt/bxi/mods

清单规划

schema: 1
id: com.customer.motion_pack
name: 客户动作包
version: 1.2.0
api: ">=4,<5"
enable: true
entrypoint: plugin:create_mod
visibility: public
requires:
  - id: com.bxi.basic_actions
    version: ">=1,<2"
conflicts: []
python_exports: []
runtime_requirements:
  python: []
  ros: []
  system: []

events:
  customer_walk:
    slot: btn_10
    value: 11
  customer_gesture:
    slot: btn_10
    value: 12
  toggle_pause:
    slot: btn_9
    value: 1

speed_profiles:
  customer_walk:
    vx_scale: 0.5
    vx_min: -0.3
    vx_max: 0.5
    vy_scale: 0.3
    yaw_scale: 0.5

transition_profiles:
  safe_entry:
    type: sequence
    steps:
      - type: hold
        duration: 0.02
      - type: entry_gain_ramp
        duration: 0.8
        kp_from: zero
        kd_from: target

states:
  customer_walk:
    manifest:
      label: 客户步态
      priority: 100
      group: Customer
    speed_profile: customer_walk
  customer_gesture:
    manifest:
      label: 客户动作
      priority: 90
      group: Customer
      confirm: true
      confirm_message: 请确保周围安全

routes:
  - from: com.bxi.basic_actions/normal
    event: customer_walk
    to: customer_walk
    transition: safe_entry
  - from: com.bxi.basic_actions/normal
    event: customer_gesture
    to: customer_gesture
    transition: safe_entry
  - from: customer_walk
    event: com.bxi.basic_actions/normal
    to: com.bxi.basic_actions/normal
    transition: dual_running_blend
  - from: customer_gesture
    event: com.bxi.basic_actions/normal
    to: com.bxi.basic_actions/normal
    transition: dual_running_blend
  - from: customer_gesture
    event: com.bxi.basic_actions/zero_torque
    to: com.bxi.basic_actions/zero_torque

actions:
  - from: customer_gesture
    event: toggle_pause
    action: toggle_pause
    manifest:
      label: 暂停/继续

btn_10=11/12 是客户扩展值，不在默认遥控器绑定中。部署这个动作包时需增加相应 output， 并把槽位/值冲突检查作为整机配置校验的一部分。

这里把 route 和 Transition 分开规划：route 决定事件触发后的目标状态，Transition 负责切换期间的电机帧。模型之间的 qpos/kp/kd 可能不连续，所以进入时逐步建立目标控制力，返回行走时混合两边的运行输出，避免直接换帧产生突跳。

插件边界

• 资源 factory 只解析 Mod 内资产。
• 两个状态共享的模型只注册一次。
• 所有清单参数由 StateBuildContext 消费。
• 业务过渡类由 ModDefinition.transition_plugins 显式注册。
• 状态的 ROS 资源在 on_bind/on_unbind 对称管理。

安全策略

• 高风险入口使用 manifest.confirm。
• 姿态异常时主动请求 com.bxi.basic_actions/zero_torque。
• 模型完成时明确返回基础 normal 或 pd_brake。
• 进入模型前预热，过渡取消时撤销临时状态。
• 真机默认速度 profile 从保守范围开始。

重启与加载失败验证

分别测试：

1. 修改清单参数并重启，确认新参数生效。
2. 替换模型并重启，确认新模型加载成功。
3. 故意制造工厂/状态键不匹配，确认节点启动失败并给出明确错误。
4. 恢复上一个有效 Mod 目录并重启，确认系统恢复运行。
5. 删除一个 Mod 后重启，确认保留 Mod 的依赖闭包和初始状态仍然有效。

发布策略

整个客户包需要从公开版删除时添加：

visibility: protected

随后运行 sanitizer 自检。若只保护其中一个动作，应先把它拆成独立 Mod；发布工具不会裁剪包内单个状态。

工程化检查

1. Mod id、资源 key、过渡 type 全局唯一。
2. 跨 Mod route 均有依赖。
3. 普通状态只写 priority；确需固定 index 时保证全局唯一，重复值会阻止启动。
4. 输入输出槽位已与遥控器配置对齐。
5. 所有状态能力满足实际 transition profile。
6. 仿真、启动失败清理、重启恢复和公开树都已验证。