Advanced Recipes

高级配置范式

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

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

最小跨 Mod 切换

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

events:
  activate:
    slot: btn_10
    value: 11

states:
  custom:
    manifest:
      label: 自定义
      priority: 100

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: 11

遥控器 YAML 可让键盘、手柄和 CRSF 的不同 control 都输出 btn_10=11。状态 Mod 无需知道输入设备。示例值 11 不是默认绑定；部署前应在整棵 Mod 树中确认槽位和值唯一，再增加对应 output。

延迟切换

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
actions:
  - from: custom
    event: toggle_pause
    action: toggle_pause
    manifest:
      label: 暂停/继续

状态的 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
name: 共享策略资源
version: 1.0.0
api: ">=4,<5"
enable: true
entrypoint: plugin:create_mod
visibility: public
requires: []
conflicts: []
python_exports: []
runtime_requirements:
  python: []
  ros: []
  system: []
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 规划

普通状态使用 manifest.priority 排序，由框架生成唯一 index。只有外部协议确实要求固定 位置时才显式声明 manifest.index，并在整棵状态树中保证唯一；两个显式 index 重复会 直接阻止启动，不会自动向后重排。

工程检查清单

1. 所有跨 Mod 引用都有 requires。
2. 资源路径均在所属 assets/。
3. 参数由 StateBuildContext 强类型消费。
4. action 有 handler，事件至少有一条 route 或 action。
5. running_blend 的 advance 语义正确。
6. on_bind/on_unbind 和资源 close() 对称。
7. 修改 Mod 后重启节点，验证成功加载以及错误配置能在启动阶段明确失败。
8. 发布前运行 sanitizer --self-check。