Model And Launch

模型、资源与 launch

模型和动作数据属于使用它们的 Mod，放在该 Mod 的 assets/。运行时通过资源管理器按声明的 eager/lazy 策略加载，不再把模型对象动态挂到 BxiExample。

文件布局

mods/com.example.motion/
  mod.yaml
  plugin.py
  state.py
  assets/
    motion.npz
    policy.onnx

setup.py 会递归安装整个 mods/，同时跳过 __pycache__、.pyc 和 .pyo。

注册资源

from bxi_example_py_elf3.framework.mod_api import (
    ModDefinition,
    ModLoadContext,
    ResourceKey,
    ResourceLoadContext,
)

POLICY = ResourceKey[MotionPolicy]("com.example.motion/policy")


def _load(context: ResourceLoadContext) -> MotionPolicy:
    return MotionPolicy(
        str(context.asset("assets/motion.npz")),
        str(context.asset("assets/policy.onnx")),
    )


def create_mod(context: ModLoadContext) -> ModDefinition:
    context.register_resource(POLICY, _load, loading="eager")
    policy = context.resource(POLICY)
    return ModDefinition(
        state_factories={
            "motion": lambda state: MotionState(
                state.name, state.state_id, policy
            )
        }
    )

ResourceKey 必须全局命名。context.asset() 会拒绝逃出当前 Mod assets/ 的路径，并确认文件存在。

加载策略

context.resource(POLICY) 只返回 ResourceHandle。loading="lazy" 在状态 第一次调用 handle.get() 时创建模型，适合不常进入的动作；loading="eager" 在框架启动、控制定时器开始前创建模型，适合加载时间较长且切换时不能阻塞的 策略。之后都返回相同实例。加载策略硬编码在资源注册代码中，不写入 mod.yaml。

节点关闭时，资源管理器会按逆序调用已加载实例的 close()（若存在），然后清空缓存。

多个状态共享模型时，让它们持有同一个 handle。多个 Mod 共享模型时，优先拆出一个无状态资源 Mod，并用 requires 声明依赖。

状态内使用

class MotionState(RobotControlState, EntryFrameProvider):
    def __init__(self, name, state_id, policy):
        super().__init__(name, state_id)
        self._policy = policy

    @property
    def policy(self):
        return self._policy.get()

    def on_prepare(self, ctx, from_state):
        self.policy.timestep = self.policy.start_frame
        ctx.preheat_model(self.policy)

模型预热放 on_prepare()，不要在插件加载或状态构造阶段执行推理。进入失败时可在 on_prepare_cancel() 撤销临时状态。

当前资产路径

基础动作模型位于 mods/com.bxi.basic_actions/assets/。后空翻、前空翻、芭蕾舞和深度感知行走资产分别位于各自独立 Mod 的 assets/。

深度感知行走的模型和策略都属于 com.bxi.normal_depth Mod；策略实现位于 mods/com.bxi.normal_depth/depth.py，只依赖通用 framework/inference，公共 policies 不会 反向导入它。可替换的相机或感知节点通过标准 ROS 话题接入，不属于模型 Resource。

example_walk.launch.py 和硬件版本中给独立 MJLab 节点使用的模型路径是：

mods/com.bxi.basic_actions/assets/model_normal.onnx

launch 的职责

launch 负责启动仿真或硬件、设置 /topic_prefix、覆盖 /state_machine_config 和状态信息参数。Mod 自己使用的模型路径不应硬编码进 launch；由资源加载函数相对 Mod 根解析。

验证

colcon build --packages-select bxi_example_py_elf3 --symlink-install --merge-install
find install/share/bxi_example_py_elf3/mods -name mod.yaml -o -path '*/assets/*'

若工作区此前使用过不同 install layout 或旧资产目录，请使用新的 build/install 路径，或只清理该包的旧构建缓存。