前言

2026 年 8 月，Pollen Robotics（已并入 Hugging Face）发布了 Microduck：一台 25 厘米高、约 800 克、售价 399 美元的双足机器鸭。它真正的价值不在硬件——14 个 Dynamixel 舵机、一颗 Rockchip SoC，这些都是成熟供应链里的东西——而在于它把一整套从仿真训练到真机部署的物理 AI 流水线连同机器人操作系统全部开源了出来。

RL 仓库 AGENTS.md 的第一段有一句话，是这本书的题眼：

Sim2real transfer is the whole point: every convention below exists because breaking it produced a policy that worked in the viewer and failed on hardware.

（Sim2real 迁移就是全部意义：下文每一条约定的存在，都是因为打破它曾产出一个在查看器里工作、上机就翻车的策略。）

v0.2 的这次扩写，做的就是把这些"约定"逐条挖出来的工作。两个仓库克隆到本地逐文件读过后，我发现它们最珍贵的不是架构图，而是注释里的事故记录：哪个 wandb run 用 0.1 的容差把策略练到再也不走路、哪次累积式随机化让长训劣化了数月、哪块板子因为两处版本漂移装上了会让运行时 panic 的旧库。这些内容教科书里没有，论文里更没有——它们只存在于"把系统真正跑起来的地方"。

因此 v0.2 每章都加了代码走读：引用一律逐字摘录（含原注释与实验数字），读者可以拿着书对着仓库读。全书的高光段落包括：

• robotd 里 COAST_TICKS = 3 的完整论证——为什么每分钟 8 次的总线丢包必须对用户不可见（第 4 章）；
• 奖励"头部下垂之战"——一次失败收紧、一次 EMA 手术，及其背后的普适原则"只罚可逃避的错误"（第 8 章）；
• BacklashEncoderBamActuator——同一个 get_command 里，位置走编码器侧、速度留在转子侧，一行代码里的执行器物理学（第 9 章）；
• 导出-发布-安装链的三重互锁——归一化器烘焙进图、发布器直调导出器、上传侧替设备先拒坏文件（第 10 章）。

如何读这本书：有 Rust 基础的读者顺序读上半部（1–6 章）再跳第 10 章；做强化学习的读者从第 7 章直入（第 8、9 章是重点）；只想跑通流程的读者读第 6、7 章加各章末的命令清单。每章开头的引言块标注了该章走读的源码文件，附录 B 有完整的文件-章节对照表。

致谢：所有素材来自 Pollen Robotics 的公开博客、两个 GitHub 仓库（Apache-2.0）及社区报道。特别感谢把失败实验写进注释的工程师们——那些注释是这本书真正的作者。