Hands On Series

手把手系列总览

这组课程以当前 Mod 架构为准。完成后应能独立交付一个带状态、模型、按键、过渡、热重载和发布属性的客户 Mod。

第一次接触框架，先完成 从两文件状态到自定义 Driver。它固定使用同一个 Mod ID、状态名和 routes，依次完成：

PoseState -> ProceduralState -> PolicyState / MotionReplayState
-> RobotControlState -> Resource -> Transition -> ROS -> Driver

下面的专题课再对每个高级方向展开。

学习路径

第 1 课：自定义状态 Mod

开始学习

• 创建两文件 Mod，再按需增加 plugin.py。
• 从 PoseState/ProceduralState 开始，按需下沉到 RobotControlState。
• 用 dataclass 或 StateBuildContext 读取参数。
• 在清单中声明依赖、状态和 route。

第 2 课：模型动作 Mod

开始学习

• 把 .npz/.onnx 放进 assets/。
• 使用 ResourceKey 和惰性 ResourceHandle。
• 在 on_prepare() 预热。
• 处理播放结束、暂停和安全退出。

第 3 课：控制器绑定

开始学习

• 从 source 到 control 再到 edge output。
• 一个 Mod event 同时支持键盘、手柄和 CRSF。
• 从 /motion_commands 追踪到完整状态名。

第 4 课：Mod 内自定义过渡

开始学习

• 实现 SingleClassTransition。
• 由 entrypoint 导入并参与热重载回滚。
• 用状态能力协议做加载期验证。

第 5 课：双状态运行混合

开始学习

• 实现 RunningFrameProvider。
• 理解 sample_from/to 和 advance_from/to。
• 在 Mod route 中使用系统共享 profile。

第 6 课：自定义输入驱动

开始学习

• 实现非阻塞设备驱动和工厂。
• 接入设备优先级、抢占和断连回退。
• Driver 只输出 raw signal。

第 7 课：工程化组合

开始学习

• 拆分动作、资源和依赖。
• 配置热重载、发布保护和离线自检。
• 建立可维护的命名、index 和安全策略。

第 8 课：Sim2Real

开始学习

• 明确策略输入输出和关节顺序。
• 在仿真、低增益和真机之间分阶段验证。
• 把模型版本和运行参数封装进 Mod。

读完后的能力

• 无需修改状态机核心即可新增动作。
• 无需把模型挂到节点属性即可共享和释放资源。
• 能解释完整名称、Mod 依赖和发布闭包。
• 能定位输入、事件、route、过渡和状态输出中的故障层。
• 能用 visibility: protected 安全地产生公开版本。