Architecture

架构总览

当前架构把输入、状态图、动作实现和模型资产分为四层。状态侧的部署单元是 Mod，不再依赖中央状态类文件。

总数据流

手柄 / 键盘 / CRSF / 自定义设备
  -> InputDeviceManager
  -> InputDriver
  -> sources -> controls -> outputs
  -> communication/msg/MotionCommands
  -> RemoteEventAdapter
  -> RobotStateMachine
  -> RobotControlState
  -> MotorFrame / set_motor_target()
  -> ActuatorCmds

配置和代码的加载流：

elf3_state_machine.yaml（系统配置）
  + 内置 mods/
  + mod_paths 中的客户 Mod
  -> 发现 mod.yaml
  -> 校验依赖并排序
  -> 加载 entrypoint
  -> 注册惰性资源和状态工厂
  -> 合成 states/events/routes/profiles
  -> 构建 RobotStateMachine

文件分层

src/remote_controller/
  config/xbox_default.yaml
  include/remote_controller/
  src/

src/bxi_example_py_elf3/
  config/elf3_state_machine.yaml       # 系统级配置
  mods/
    com.bxi.basic_actions/
      mod.yaml                         # 状态图贡献
      plugin.py                        # 工厂和资源注册
      *_state.py                       # 状态实现
      assets/                          # 该 Mod 私有资产
    com.bxi.back_flip/
    com.bxi.forward_flip/
    com.bxi.ballet/
  bxi_example_py_elf3/
    bxi_example_demo.py
    inference/
    transitions/                       # 内置过渡类型
    utils/
      mod_system.py
      robot_state_builder.py
      robot_state_base.py
      state_library.py                 # 渐进式状态基类和动作回放状态
      state_machine.py
      transition_core.py
      hot_reload.py

运行时对象

对象	责任
ModRuntime	保存合成配置、状态工厂、资源管理器、已加载 Mod 和动态模块
ResourceManager	注册、惰性创建、缓存和关闭资源
StateBuildContext	为状态工厂提供名称、稳定 state id 和强类型参数读取
RobotStateMachine	处理事件、延迟、过渡、状态生命周期和图导出
RemoteEventAdapter	把 MotionCommands 槽位变化转成 Mod 事件
HotReloadMixin	原子重建整个 Mod 运行时，失败时保留旧运行时

命名空间

Mod 清单中的本地名称会自动限定：

Mod id:       com.example.wave
state:        wave
event:        activate
resource:     com.example.wave/policy

运行时状态:  com.example.wave/wave
运行时事件:  com.example.wave/activate

同一 Mod 内的 from: wave、to: wave 和 event: activate 会自动限定。跨 Mod 引用必须写完整名称，并通过 requires 声明依赖。

修改边界

新增动作：

• 新建或扩展一个 Mod。
• 在 mod.yaml 声明状态、事件和路由。
• 简单状态用 factory: module:Class；需要资源和扩展注册时再由 plugin.py 返回工厂。
• 模型放进该 Mod 的 assets/ 并注册资源。
• 在遥控器 YAML 中输出清单所使用的 btn_N=value。

新增过渡：

• 框架通用过渡放入包内 transitions/。
• 业务专用过渡放在对应 Mod 中，并由 plugin.py 导入以触发注册。
• profile 可放系统 YAML；Mod 私有 profile 放 mod.yaml，会自动加命名空间。

新增输入协议：

• 先判断是否仅靠遥控器 YAML 能完成。
• 必须读新设备时再实现 InputDriverBase 和工厂。
• Driver 只产生 raw signal，不直接写状态名。

公开发布：

• 在要整体移除的 Mod 清单中设置 visibility: protected。
• tools/sanitize_release.py 删除整个目录并验证保留 Mod 的依赖闭包。

下一步

• Mod 系统
• 状态机基础配置
• 自定义状态
• 框架底层运行原理