Migration From 0f90a49

从 0f90a49 迁移到当前 Mod 架构

本页总结 0f90a49c539e0efcec0d6fbc481f634890742c78 之后影响使用方的主要变化。

从 Mod API 3 迁移到 API 4

当前框架公开 MOD_API_VERSION = "4.0.0"，清单必须改为：

api: ">=4,<5"

API 4 把模型加载从控制生命周期中移到异步 Resource 准备流程：

API 3	API 4
loading="eager"	policy="startup"
loading="lazy"	policy="on_demand"
handle.get() 首次调用时同步加载	handle.get() 只读取已经 ready 的实例
状态在 on_prepare() 才发现模型未加载	状态构造时用 resources=(handle,) 声明依赖
PolicyState.create_policy()	Resource factory 创建策略，构造函数接收 handle

自定义核心状态应这样声明资源：

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

PolicyState 和 MotionReplayState 在接收 handle 后会自动声明依赖。请求一个使用 on_demand 资源的状态时，状态机会保持当前状态、异步准备资源，并在 state_machine_info.preparing 中发布进度；就绪后才调用目标状态的 on_prepare()。

ctx.preheat_model() 的速度参数现在统一为 command=...，不再接受 with_cmd_vel 或 cmd_vel。运行时显示 logger 也缩短为 fw.* 和 <mod-id>.*，但 logging.levels 配置仍使用逻辑 scope framework.* 与 mod.*。

已删除的入口

以下旧入口不再存在：

bxi_example_py_elf3/robot_states.py
config/release_protection.yaml
data/isaaclab_model/
data/mjlab_model/

中央状态 YAML 中的 states、remote_events 和 speed_profiles 也不再作为配置源。

新的对应关系

旧方式	当前方式
在中央文件添加 State class	在 Mod 目录添加状态模块
构建器扫描所有 State 子类	plugin.py 返回显式 state_factories
中央 YAML 声明状态和边	mod.yaml 声明 states/events/routes/actions
模型挂在 ctx 动态属性	ResourceKey + ResourceHandle
模型放 data/*_model	模型放所属 Mod 的 assets/
按单个类/模型做发布删除	visibility: protected 删除整个 Mod
热重载中央状态模块	不再支持运行时重载；修改后重启控制节点

状态名变化

基础动作已经合并到：

com.bxi.basic_actions

例如：

旧：com.bxi.normal/normal
新：com.bxi.basic_actions/normal

旧：com.bxi.zero_torque/zero_torque
新：com.bxi.basic_actions/zero_torque

基础事件也变为动作名：

com.bxi.basic_actions/normal
com.bxi.basic_actions/zero_torque
com.bxi.basic_actions/dance

后空翻、前空翻和芭蕾舞仍是独立 Mod，其入口事件是各自的 activate。

迁移一个旧状态

1. 创建 mods/com.example.action/。
2. 把状态类移到 state.py。
3. 把模型和动作数据移到 assets/。
4. 创建 plugin.py，注册资源并返回状态工厂。
5. 显式填写 schema/id/name/version/api/enable/entrypoint/visibility/requires/conflicts/python_exports/runtime_requirements；没有内容的列表写 []，runtime_requirements 的 python/ros/system 三类都要显式填写。
6. 把中央 YAML 的状态、事件和边改写为 mod.yaml 的 states/events/routes/actions。
7. 跨包引用改成完整名称并写入 requires，不能共存的 Mod 写入 conflicts。
8. 遥控器输出槽位可以保持不变。

完整模板见 手把手自定义状态 和 模型动作 Mod。

发布迁移

旧的类名、模型键和路径删除清单全部移除。现在只需在高危 Mod 中写：

visibility: protected

然后运行：

python3 tools/sanitize_release.py --out /tmp/public_release --self-check

工具会检查跨 Mod route 推导出的依赖和显式 requires，防止公开 Mod 依赖被删除 Mod。

运行时更新方式

/hot_reload 参数已经删除。系统 YAML、Mod 清单、状态代码、Transition 或模型资产发生变化后，需要重启控制节点。所有发现、依赖排序、资源注册和状态图校验都在启动阶段完成；运行期间不扫描文件，也不替换状态机对象。

状态显示顺序

普通 Mod 不再手工维护 manifest.index，改为声明整数 manifest.priority：数值越大越靠前，相同 priority 按完整状态名升序排列，框架自动生成唯一 index。确实需要固定位置时仍可显式声明非负 index，但两个显式 index 重复会直接终止启动。