Advanced Recipes

高级配置范式

以下片段均基于当前 Mod 架构。

下面出现的 Transition 都是在 route 已决定目标状态后，负责切换期间电机输出的策略。它用于处理源、目标状态之间可能不连续的 qpos/kp/kd；没有合适过渡时直接换帧，机器人可能突然动作。

最小跨 Mod 切换

requires:
  - id: com.bxi.basic_actions
    version: ">=1,<2"

events:
  activate: {slot: btn_10, value: 8}

states:
  custom: {manifest: {label: 自定义, index: 20}}

routes:
  - {from: com.bxi.basic_actions/normal, event: activate, to: custom}
  - {from: custom, event: com.bxi.basic_actions/normal, to: com.bxi.basic_actions/normal}

同一事件支持多种设备

状态侧只声明一个槽位：

events:
  activate: {slot: btn_10, value: 8}

遥控器 YAML 可让键盘、手柄和 CRSF 的不同 control 都输出 btn_10=8。状态 Mod 无需知道输入设备。

延迟切换

routes:
  - from: custom
    event: stop
    to: com.bxi.basic_actions/zero_torque
    delay: 0.2

新 event 到来可覆盖 pending transition；安全事件应使用立即路由。

状态内部 action

events:
  toggle_pause: {slot: btn_9, value: 1}
routes:
  - {from: custom, event: toggle_pause, action: toggle_pause}

状态的 on_action() 返回 true 表示已处理。

单次覆盖过渡

transition:
  profile: dual_running_blend
  duration: 1.0
  curve: smootherstep
  sample_from: false

Mod 私有过渡

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

运行时 profile 名自动变为 mod-id/safe_entry。

共享资源 Mod

资源提供者可使用：

schema: 1
id: com.example.shared_policy
version: 1.0.0
api: 1
entrypoint: plugin:create_mod
states: {}

消费 Mod 通过 requires 依赖它，并使用相同完整 ResourceKey。公开资源 Mod 不应依赖 protected 功能。

客户 Mod 外置部署

系统 YAML：

mod_paths:
  - /opt/bxi/mods

客户包可独立复制到该目录，无需修改 ROS Python 包。id 必须避免与内置 Mod 重复。

Python 公共包导出

python_exports:
  - customer_common

适合多个 Mod 共享纯 Python helper。目录必须包含 __init__.py，导出名全局唯一。更简单的共享资源优先使用资源 Mod。

高危动作发布保护

visibility: protected

保护整包而不是列类名、模型键和路径。公开 Mod 若引用它，sanitizer 会拒绝生成。

index 规划

团队仍应为不同产品预留区间，但加载器可容忍意外冲突：首次声明者保留，后续冲突状态自动向后寻找空位。把警告当成需要整理清单的信号，而不是长期依赖动态排序。

工程检查清单

1. 所有跨 Mod 引用都有 requires。
2. 资源路径均在所属 assets/。
3. 参数由 StateBuildContext 强类型消费。
4. action 有 handler，事件至少有一条 route。
5. running_blend 的 advance 语义正确。
6. on_bind/on_unbind 和资源 close() 对称。
7. 开启热重载后验证成功与失败回滚。
8. 发布前运行 sanitizer --self-check。