# Microduck 策略怎么分享：ONNX 模型从训练到一键安装的真机流程
做过机器人 RL 的人都知道，训练出一个能走的策略只是成功了一半。另一半是怎么把这个策略从训练机器搬到真机上，还能让别人用。Microduck 有一套完整的策略分发链路：训练完的模型导出成 ONNX，发布到 Hugging Face Hub，任何一只 Microduck 都能通过一条命令安装。今天拆开看这条链路。
从 checkpoint 到 ONNX：不是简单转格式
microduck_rl 的 scripts/export.py 是策略导出的唯一正规路径。为什么强调”唯一”？因为这一步不只是把 PyTorch 的 .pt 文件转成 .onnx——它还做了一件关键的事：把观测归一化器烙进 ONNX 图里。
训练时策略网络看到的输入是归一化后的观测值。如果导出时没把归一化步骤一起写进 ONNX，部署时策略看到的就是原始观测值，数值范围完全不对，鸭子直接摔。AGENTS.md 里用粗体写了这条规则：永远用 scripts/export.py 导出，不要手动转换 checkpoint。
导出后的 ONNX 模型形状是固定的：输入 [1, 61]，输出 [1, 14]。61 是观测维度（48 维本体感知加 13 维指令块），14 是舵机数量。publish 命令上传前会验证这个形状——如果模型输出是 51 维（旧版策略），直接被拒。
manifest.json：策略的身份证
每个发布到 Hugging Face Hub 的策略仓库里有两个文件：policy.onnx 和 manifest.json。manifest 是策略的元数据，遵循 schema 2 格式。机器人读 manifest 来决定怎么运行这个策略。
几个关键字段：
kind：策略类型。episodic是一次性技能（踢球、翻滚、鞠躬），跑完duration_s秒后自动回到站立姿态。perpetual是持续策略（步态、站姿），一直跑直到被切换。scripted是可中断的 episodic，守护进程能在执行中途改变指令。command.encoding：指令编码方式。constant是固定指令，大多数技能用这个。phase是相位驱动，地面拾取任务用。posture_flag是姿态标志，坐站切换用。obs_len和action_len：观测和动作维度。机器人会验证这两个值，不匹配直接拒绝加载。model_api：策略需要的守护进程 API 版本。策略要求的版本比机器人上的守护进程新，会被拒绝。
这套验证的设计原则是”只拒绝明确错误的声明，不猜测缺失的字段”。manifest 里大部分字段可选，缺失不等于错误。只有当某个字段存在且值不对时才拒绝。
发布流程：四步从 wandb 到 Hub
uv run publish 是一条龙命令，做四件事。
第一步，如果给的是 wandb run path 而不是已有 ONNX 文件，先导出 ONNX。第二步，验证 ONNX 图的形状和输出——跑几组测试输入，拒绝 NaN 输出或常数输出。第三步，构建 manifest.json，从 git 和 wandb 里填充训练信息：任务 ID、commit hash、分支、checkpoint 编号、导出时间戳。第四步，上传到 Hugging Face Hub，默认创建私有仓库。
发布时必须指定 --kind。episodic 策略要给 --duration-s 告诉机器人跑多久。perpetual 步态策略要给 --slot walk 或 --slot stand 说明装到哪个槽位。--description 是一句话描述，robotctl policy search 时会显示。
一个有意思的细节是 --base-model 参数。基于别人的策略做了微调，指定 base model 后，Hugging Face Hub 的 model card 会自动链接到原始策略，就像 GitHub 的 fork 关系。策略的衍生谱系因此可追溯。
真机安装：两条路径
策略到了 Hub 上之后，真机端有两种安装方式。
robotctl policy load walk 把策略装到指定槽位。这是步态策略的安装方式，装完后机器人启动时自动加载。
robotctl policy add polite-bow 把策略注册为技能。技能按需触发，用 robotctl robot do polite-bow 执行。perpetual 类型的技能（比如金鸡独立）加 --hold 5 指定保持 5 秒。
安装时机器人做几项检查：obs_len 必须是 61，action_len 必须是 14，robot.model 必须是 microduck，model_api 不能比当前守护进程版本新。episodic 类型还会检查 command.encoding——只有 constant 编码的 episodic 策略能通过 policy add 安装为通用技能。phase 和 posture_flag 编码的策略必须通过 policy load 装到守护进程驱动的专用槽位。
官方策略集和社区策略
Microduck 有两种策略来源。官方策略集 pollen-robotics/microduck-policies 是一个包含十个策略的合集仓库，manifest.json 里的 policies[] 数组列出每个策略的文件和参数。官方集包含所有相位驱动和姿态标志类型的策略——这些策略的指令由守护进程生成，不能作为社区通用技能发布。
社区策略是单策略仓库，格式 robotctl policy search 搜索 Hub 上的社区策略，结果显示描述和预览视频。
预览视频不是 manifest 里的字段，是文件路径约定。仓库里有 media/preview.mp4，搜索结果就链接这个视频。这个设计不需要额外的 manifest 字段，直接利用发布者本来就会上传的视频文件。
episodic 和 perpetual 的生命周期
episodic 策略有一个明确的生命周期：触发，运行 duration_s 秒，回到安全姿态，结束。chain 设为 true 时按住按钮会连续触发，比如连续踢球。
perpetual 策略没有结束时间。步态策略一直运行直到被另一个步态策略替换。姿态技能（比如单腿站立）运行 unwind_s 秒后把控制权交回步态策略。这个”交回”不是瞬间切换——守护进程先驱动一个 command.idle（通常零速指令）让鸭子减速到停，然后才切回步态。如果在单腿站立时直接切回步态策略，鸭子可能还在单腿状态，步态策略接手后立刻摔。
发布前最后的安全网
scripts/infer_policy.py 是发布前最后的自测工具。它在 CPU MuJoCo 里跑导出的 ONNX，用键盘发指令，模拟真机部署。可以用 --walking、--standing、--sitstand 等参数同时加载多个策略，测试热切换。
这个工具用的是和训练相同的 BAM M6 执行器模型。--vin 和 --no-bam 参数可以把域随机化范围钉到固定值或退回理想 PD 执行器，用来做 A/B 对比。如果 --no-bam 模式下策略立刻摔了，说明策略确实依赖了 BAM 的物理建模，sim2real gap 被 DR 覆盖了。
策略在真机上表现不好怎么办？用 robotctl policy load walk pollen-robotics/microduck-policies 恢复官方步态。策略按槽位安装，替换不需要卸载，直接 load 新的覆盖旧的。
数据来源：pollen-robotics/microduck_rl README（发布命令和策略类型说明），pollen-robotics/microduck 仓库 docs/policy-manifest.md（schema 2 完整规范），pollen-robotics/microduck_rl AGENTS.md（导出规则和不变量）。
