Migration From 0f90a49

从 0f90a49 迁移到当前 Mod 架构

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

已删除的入口

以下旧入口不再存在：

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 重复会直接终止启动。