运动控制公共基础层建设计划¶
版本: v0.1 草案 | 日期: 2026-05-11 定位: 为
05_运动控制下机械臂、足式、复合、仿真四个子方向建立统一的公共知识层 状态: 规划文档。本文件只定义重构原则、目录草案、迁移顺序和质量门禁，不替代现有章节正文
0. 为什么需要公共基础层¶
05_运动控制 目前已经形成四个相对独立的子方向：
| 子方向 | 当前目录 | 核心问题 |
|---|---|---|
| 机械臂 | 机械臂/ |
固定基座、全驱动关节、末端操作、工业集成、力控与双臂 |
| 足式 | 足式/ |
浮动基座、离散接触、步态、MPC/WBC、RL locomotion |
| 复合 | 复合/ |
底盘-机械臂耦合、轮足、人形、移动操作、全身控制 |
| 仿真 | 仿真/ |
MuJoCo/Isaac/MJX/Genesis、可微仿真、GPU 并行、Sim-to-Real |
这四个方向的机器人本体不同，但底层工具和数学结构高度重叠。例如：
- 机械臂和足式都需要 Pinocchio、RNEA/ABA/CRBA、Jacobian、碰撞几何。
- 机械臂 IK-QP、足式 WBC-QP、复合全身 QP 都共享同一套约束优化语言。
- 自动微分、代码生成、CasADi、CppAD 在轨迹优化、MPC、系统辨识中反复出现。
- 实时 C++、无堆分配、
ros2_control、硬件抽象是所有真机部署共同的底层能力。 - URDF/Xacro/MJCF、惯量检查、碰撞体、域随机化和系统辨识贯穿机械臂、足式和仿真。
如果这些公共内容长期散落在各个子方向中，会带来三个问题：
- 维护成本高：同一个公式或 API 需要在多处修复，容易出现一处正确、一处过期。
- 学习路径重复：读者切换方向时会反复学习同一套基础，但符号约定和版本信息可能不同。
- 知识边界模糊：公共理论、方向特化和工程案例混在一起，不利于后续扩展轮足、人形、灵巧手等内容。
因此，建议在 05_运动控制/ 下新增 00_公共基础/，把跨方向共享的基础知识统一收口。
本质判断：公共基础层不是把各方向文档“抽空”，而是建立一个稳定的知识地基。方向文档仍然负责讲清本方向的物理问题、工程取舍和实战案例；公共基础负责统一符号、公式、API、工具链和跨方向复用逻辑。
1. 建设目标与非目标¶
1.1 建设目标¶
公共基础层要解决下面五类问题：
| 目标 | 具体含义 | 预期效果 |
|---|---|---|
| 统一符号 | 对空间速度、Jacobian、接触力、QP 变量、阻抗误差等给出全局约定 | 后续公式复核只需要检查一套基准 |
| 统一工具 | 把 Pinocchio、CasADi、CppAD、OSQP、MuJoCo、ros2_control 等公共工具集中讲解 | 各方向不再重复基础 API |
| 统一工程陷阱 | 汇总惯量错误、关节索引、实时内存、符号约定、仿真资产等失败经验 | 经验从“章节局部”变成“全局资产” |
| 支撑四方向阅读 | 为机械臂、足式、复合、仿真提供共同前置 | 读者能先补公共基础，再进入任一方向 |
| 降低后续维护成本 | 版本信息、公式推导、API 约定集中维护 | 减少重复修复和交叉引用错位 |
1.2 非目标¶
公共基础层不应该做下面几件事：
| 非目标 | 原因 |
|---|---|
| 不替代机械臂、足式、复合、仿真正文 | 每个方向仍有自己的物理场景和工程叙事 |
| 不把所有重复文字机械搬运到公共层 | 机械搬运会破坏章节连续性，也会制造新的冗余 |
| 不删除方向文档中的必要回顾桥 | 单章阅读仍然需要 2-3 段前置激活 |
| 不把版本敏感内容写成永久结论 | MoveIt2、Isaac Lab、Pinocchio、cuRobo 等生态变化快，需要注明查询日期和版本锚点 |
| 不一次性大规模移动文件 | 大规模改路径会破坏引用、导航和读者习惯，应采用渐进迁移 |
2. 推荐目录结构¶
建议公共基础层采用 Bxx 编号，表示 Base / Common Foundation，避免和机械臂 Mxx、足式 Chxx、仿真 Sxx 冲突。
05_运动控制/
00_公共基础/
B00_导读_公共基础与四方向复用地图.md
B01_机器人描述与资产管道_URDF_Xacro_MJCF.md
B02_刚体动力学库与Pinocchio基础.md
B03_空间向量_浮动基座_统一动力学基础.md
B04_约束优化_QP_NLP_求解器基础.md
B05_自动微分_符号计算_代码生成基础.md
B06_碰撞几何_SDF_距离梯度基础.md
B07_接触力学_摩擦锥_互补约束基础.md
B08_实时C++_PREEMPT_RT_无堆分配基础.md
B09_ros2_control_硬件抽象_通信基础.md
B10_仿真接口_MuJoCo_MJCF_SimToReal基础.md
B11_RL部署与SimToReal公共方法.md
B99_公共基础索引_术语_API速查.md
2.1 各章节定位¶
| 章节 | 定位 | 不应纳入的内容 |
|---|---|---|
| B00 | 公共基础层导读、四方向依赖图、学习路径 | 具体库 API 长篇教学 |
| B01 | URDF/Xacro/MJCF、mesh、惯量、坐标系、资产检查 | Panda/Go2/H1 的完整项目配置 |
| B02 | Pinocchio Model/Data、RNEA/ABA/CRBA、Jacobian、约束动力学基础 | 方向专用的完整控制器实现 |
| B03 | 空间向量、自由浮动基、选择矩阵、质心动力学统一语言 | 足式步态、复合移动操作任务细节 |
| B04 | QP/NLP 标准形、KKT、求解器、warm start、数值尺度 | 机械臂 IK-QP 或足式 WBC-QP 的完整章节 |
| B05 | 自动微分、符号验证、CppAD/CasADi/CodeGen、公式复核流程 | 某个方向的完整 MPC 代码生成工程 |
| B06 | 几何碰撞、GJK/EPA、SDF、距离梯度、Coal/FCL | 接触力优化和摩擦锥动力学 |
| B07 | 接触 Jacobian、摩擦锥、互补约束、接触冲量、软接触 | 纯几何碰撞检测细节 |
| B08 | 实时 Linux、调度、内存、lock-free、实时日志、性能追踪 | 具体机器人项目的所有线程代码 |
| B09 | ros2_control 架构、HardwareInterface、控制器链、通信抽象 |
Franka/Unitree/UR 的完整硬件教程 |
| B10 | MuJoCo/MJCF、仿真 step、传感器、执行器、sysid、DR | Isaac/MuJoCo 每个环境的完整训练脚本 |
| B11 | RL policy 部署、观测归一化、延迟、动作接口、sim-to-real 共性 | 足式 gait policy 或机械臂 force policy 的完整训练章节 |
| B99 | 术语表、符号表、API 速查、常见错配清单 | 新概念的长篇推导 |
3. 与现有文档的融合关系¶
3.1 Pinocchio 与动力学¶
| 公共层目标 | 主要来源 | 方向层保留内容 |
|---|---|---|
| B02 刚体动力学库与 Pinocchio 基础 | 机械臂/M01_Pinocchio深度精读.md、足式/30_Pinocchio深度精读.md、机械臂/M02_动力学库对比.md |
机械臂保留 Panda/UR 固定基示例；足式保留 FreeFlyer、接触约束、四足状态定义 |
| B03 空间向量与统一动力学 | 足式/50_空间向量与浮动基座动力学.md、复合/20_浮动基座臂统一动力学.md |
足式保留腿足浮动基推导；复合保留底盘-臂耦合和全身坐标定义 |
迁移原则：
- 公共层讲统一符号和算法接口。
- 方向层讲“这个接口在本方向里怎么用”。
- 固定基、浮动基、移动基的差异必须在公共层给出对照表，而不是散落在三处。
3.2 优化、自动微分与代码生成¶
| 公共层目标 | 主要来源 | 方向层保留内容 |
|---|---|---|
| B04 约束优化 | 机械臂/M05_QP_NLP建模工程.md、足式/60_QP_NLP建模.md、足式/100_DDP家族与Crocoddyl.md |
机械臂保留 IK/轨迹/力控 QP 模板；足式保留 WBC/MPC 接触力 QP 和 DDP/ProxDDP |
| B05 自动微分与符号验证 | 机械臂/M06_自动微分与代码生成.md、足式/40_CppAD与代码生成.md、00_项目导航/符号计算工具指南.md |
OCS2、acados、Crocoddyl、Aligator 的方向化用法继续留在原章节 |
B05 和 00_项目导航/符号计算工具指南.md 的关系应明确区分：
| 文档 | 职责 |
|---|---|
B05_自动微分_符号计算_代码生成基础.md |
面向运动控制，解释为什么 AD/符号验证/CodeGen 是控制器工程的基础 |
00_项目导航/符号计算工具指南.md |
面向全项目，提供 SymPy、PyDy、Sage、Lean 等工具使用方法和验证模板 |
3.3 碰撞、接触与仿真¶
| 公共层目标 | 主要来源 | 方向层保留内容 |
|---|---|---|
| B06 碰撞几何 | 机械臂/M04_碰撞检测.md、仿真/S01_MuJoCo核心引擎_教学版.md、仿真/S04_可微分仿真理论.md |
机械臂保留 MoveIt collision scene、抓取避障、轨迹碰撞检查 |
| B07 接触力学 | 足式/80_接触力学与约束优化.md、机械臂/F07_浮动基座WBC理论.md、复合/180_Deep_WBC精读.md |
足式保留步态接触序列；复合保留全身接触切换 |
| B10 仿真接口 | 机械臂/P02_sim-to-real资产管道.md、仿真/S01_MuJoCo核心引擎_教学版.md、仿真/S03_GPU生态.md |
仿真方向继续保留引擎深度、GPU 后端和可微仿真专题 |
注意：B06 和 B07 必须分开。碰撞几何回答“有没有碰到、距离多少、梯度方向是什么”；接触力学回答“碰到之后力怎么传、摩擦锥怎么约束、互补条件怎么建模”。二者相关，但不是同一层问题。
3.4 实时、硬件与 Sim-to-Real¶
| 公共层目标 | 主要来源 | 方向层保留内容 |
|---|---|---|
| B08 实时 C++ | 机械臂/M11_实时CPP工程.md、足式/170_实时CPP工程.md、复合stub已删(见足式/170) |
方向层保留各自控制线程、MPC 双线程、硬件接口案例 |
B09 ros2_control 与通信 |
机械臂/M12_ros2_control与硬件驱动.md、足式/180_腿足硬件栈.md、复合/110_轮足SimToReal与硬件.md |
机械臂保留 Franka/UR；足式保留 Unitree/CAN/EtherCAT/QDD；复合保留底盘-臂同步 |
| B11 RL 部署与 Sim-to-Real | 足式/190_腿足RL训练栈.md、足式/200_RL的CPP部署.md、复合/270_SimToReal统一方法论.md、仿真/MJLab与IsaacLab_RL运控教学文档.md |
足式、复合、机械臂学习力控继续保留任务特化奖励和环境设计 |
4. 迁移策略¶
4.1 总体策略：先建立公共层，再瘦身方向文档¶
不建议直接把原章节移动或拆碎。推荐采用五步迁移：
Step 1: 新建公共基础层骨架
Step 2: 写公共基础的第一版独立章节
Step 3: 在方向文档中增加“公共基础回顾桥”
Step 4: 删除或压缩方向文档中明显重复的长篇基础段落
Step 5: 全局检查交叉引用、符号约定、公式一致性和阅读连续性
这种方式有两个好处：
- 原有章节路径稳定，不会一次性打断现有学习路线。
- 公共层可以先作为“上游权威版本”存在，等内容稳定后再逐步压缩方向文档。
4.2 方向文档改写模板¶
当某个方向章节引用公共基础时，不应只写“见 Bxx”。建议使用固定结构：
### 公共基础回顾：这里需要哪些前置
回顾 Bxx：这里已经建立了 [核心概念]。它解决的是 [公共问题]。
在本章中，我们不再重复完整推导，而是把它特化到 [本方向场景]。
| 公共概念 | 本章中的具体化 |
|----------|----------------|
| QP 标准形 | IK / WBC / 接触力分配 |
| Jacobian | 末端速度 / 足端接触 / 质心动量 |
接下来真正新增的是：[本方向特有问题]。
这样可以满足教学规范中的“跨章回顾桥”，同时避免重复铺开 500 行公共理论。
4.3 保留方向章节自洽性¶
方向文档不能变成纯索引。每章至少应保留：
| 必留内容 | 原因 |
|---|---|
| 2-3 段公共基础回顾 | 读者不翻回去也能跟上 |
| 本方向符号映射表 | 防止公共符号和方向符号断裂 |
| 一个完整工程案例 | 教学价值主要来自场景化应用 |
| 常见失败经验 | 方向差异往往体现在失败模式上 |
| 到公共层的精确链接 | 便于查公式和 API |
5. 分阶段执行计划¶
Phase 0：盘点与标注¶
目标：建立完整的“公共知识点重复矩阵”，不修改正文。
任务：
- 扫描
05_运动控制全部 Markdown 文件。 - 提取标题、公式块、代码块、版本信息、API 名称和交叉引用。
- 建立如下矩阵：
| 公共知识点 | 当前出现位置 | 重复类型 | 建议归属 | 方向层保留方式 |
|---|---|---|---|---|
| Pinocchio Model/Data | M01, 足式/30_Pinocchio深度精读 | 高重复 | B02 | 保留方向化案例 |
| QP 标准形/KKT | M05, 足式/60_QP_NLP建模, F07 | 高重复 | B04 | 保留任务模板 |
| CppAD tape | M06, 足式/40_CppAD与代码生成 | 高重复 | B05 | 保留 OCS2/轨迹优化用法 |
| PREEMPT_RT | M11, 足式/170_实时CPP工程, 足式/90_WBC分层优化与TSID | 高重复 | B08 | 保留控制线程案例 |
| ros2_control SystemInterface | M12, F10, 足式/180_腿足硬件栈 | 高重复 | B09 | 保留具体硬件 |
输出物：
公共基础层_重复矩阵.md公共基础层_交叉引用清单.md公共基础层_公式与符号约定清单.md
Phase 1：公共层骨架¶
目标：创建可导航的公共基础层，但暂不大规模搬运内容。
优先新增：
B00_导读_公共基础与四方向复用地图.mdB99_公共基础索引_术语_API速查.md- 在
运动控制方向_总大纲.md中加入公共基础层说明。
B00 必须回答：
- 为什么公共基础放在四个方向之前？
- 哪些章节是机械臂/足式/复合/仿真的共同前置？
- 哪些内容必须回到方向章节学习？
- 初学者、工程落地者、博士预备者应如何选读？
Phase 2：低风险公共章节优先落地¶
优先顺序：
| 优先级 | 章节 | 原因 |
|---|---|---|
| 1 | B04 约束优化 | M05/足式/60_QP_NLP建模 重复度高，边界清晰 |
| 2 | B05 自动微分与符号验证 | 已有工具指南支撑，适合统一公式复核流程 |
| 3 | B08 实时 C++ | 方向差异较小，工程规则可统一 |
| 4 | B09 ros2_control |
版本敏感，但抽象层可统一 |
这些章节完成后，方向文档先不删大段内容，只在开头加入公共基础引用和符号映射。
Phase 3：高耦合公共章节谨慎融合¶
第二批处理：
| 章节 | 风险 | 处理原则 |
|---|---|---|
| B02 Pinocchio | 固定基/浮动基混用容易引发符号错位 | 先统一 API 与数据结构，再讲系统类型差异 |
| B03 空间向量 | 空间速度顺序、参考点、坐标系约定容易混乱 | 必须建立全局符号表和小算例验证 |
| B06 碰撞几何 | MoveIt/Coal/MuJoCo 语义不同 | 以概念和接口层为主，避免伪统一 |
| B07 接触力学 | 足式、双臂接触、仿真接触模型层级不同 | 分清刚性约束、软接触、互补约束 |
| B10 仿真接口 | 引擎差异大 | 公共层只讲共性模型，不替代仿真方向 |
Phase 4：方向文档瘦身与重写¶
当公共层稳定后，再对方向文档做渐进瘦身。
每个被瘦身的章节都按三类处理：
| 内容类型 | 处理方式 |
|---|---|
| 公共理论长篇重复 | 移到公共层，方向层保留回顾桥 |
| 本方向特化推导 | 保留并加强 |
| 失败经验/工程陷阱 | 若跨方向通用则迁入公共层；若方向特有则保留 |
示例：
机械臂/M05_QP_NLP建模工程.md中的 QP 标准形、KKT、求解器选型可压缩，机械臂 IK-QP、力控 QP 保留。足式/60_QP_NLP建模.md中的通用求解器介绍可压缩，WBC、TOWR、OCS2 相关建模保留。机械臂/M06_自动微分与代码生成.md和足式/40_CppAD与代码生成.md的 CppAD 基础统一到 B05，方向层保留代码生成部署链。机械臂/M11_实时CPP工程.md和足式/170_实时CPP工程.md的 PREEMPT_RT、无堆分配、lock-free 原则统一到 B08，方向层保留控制循环案例。
Phase 5：全局质量门禁¶
每轮迁移后必须做检查：
| 检查项 | 方法 |
|---|---|
| 断链检查 | rg "B[0-9]{2}|M[0-9]{2}|Ch[0-9]{2}|S[0-9]{2}" 后人工核对 |
| 旧编号残留 | 搜索 M1, F1, D1, P0, Ch5 等非标准编号 |
| 公式一致性 | 对关键公式用 00_项目导航/符号计算工具指南.md 中的 SymPy/PyDy 流程复核 |
| 符号约定 | 检查 linear/angular 顺序、误差定义、Jacobian 坐标系、接触力方向 |
| 版本信息 | 所有“最新”表述必须带查询日期或版本锚点 |
| 阅读连续性 | 每个方向章节必须仍能独立读懂本章新增内容 |
| 补丁感 | 检查新增段落前后语义是否自然衔接 |
6. 推荐第一批具体产出¶
第一批不要贪多，建议只完成以下文件：
05_运动控制/00_公共基础/
B00_导读_公共基础与四方向复用地图.md
B04_约束优化_QP_NLP_求解器基础.md
B05_自动微分_符号计算_代码生成基础.md
B08_实时C++_PREEMPT_RT_无堆分配基础.md
B99_公共基础索引_术语_API速查.md
选择这五个文件的原因：
| 文件 | 为什么优先 |
|---|---|
| B00 | 没有导读，公共层会变成孤立目录 |
| B04 | QP/NLP 在机械臂、足式、复合中重复度最高 |
| B05 | 能承接符号计算工具指南，也能服务后续公式巡检 |
| B08 | 实时工程原则跨方向最稳定，适合先统一 |
| B99 | 术语和 API 索引能立刻降低交叉引用混乱 |
暂缓：
- B02/B03：动力学符号约定复杂，适合第二批。
- B06/B07：碰撞和接触容易混淆，必须先确定边界。
- B10/B11：仿真和 RL 生态变化快，适合在公共层框架稳定后处理。
7. 风险与应对¶
| 风险 | 表现 | 应对 |
|---|---|---|
| 过度抽象 | 公共层写得像手册，失去教学叙事 | 每章必须保留动机、反例、推导、工程案例 |
| 过度瘦身 | 方向文档变成到处跳转的索引 | 方向章节保留回顾桥和完整案例 |
| 符号冲突 | 固定基/浮动基、空间速度顺序、接触力方向混乱 | B99 建全局符号表，每章局部符号必须映射到全局符号 |
| 版本漂移 | MoveIt2、Pinocchio、Isaac Lab 等描述过期 | 统一使用“截至 YYYY-MM-DD 查询”的表述 |
| 交叉引用错位 | 章节编号调整后旧引用残留 | 每轮迁移后执行引用审计 |
| 内容割裂 | 公共层和方向层衔接生硬 | 使用固定“公共基础回顾桥”模板 |
| 重复没有减少 | 新增公共层后方向文档仍全文重复 | 第二阶段开始有计划地压缩方向章节中的公共理论 |
8. 验收标准¶
公共基础层建设到一个阶段时，应满足以下标准：
05_运动控制/运动控制方向_总大纲.md能清楚解释公共基础层和四个子方向的关系。- 每个公共章节都能回答“这个知识为什么跨方向复用”。
- 每个公共章节都有至少一个机械臂例子、一个足式或复合例子，避免偏向单方向。
- 每个方向章节引用公共基础时，都有 2-3 段回顾桥，不只是裸链接。
- 常见符号有唯一主约定，例如：
- 空间速度排列顺序；
- Jacobian 表达坐标系；
- 阻抗误差 \(x - x_d\) 与 \(x_d - x\) 的区别；
- 接触力方向；
- QP 标准形；
- 动量观测器中的 \(C\) 与 \(C^T\) 约定。
- 原来重复出现的基础内容至少有一个“权威出处”，其他章节只做方向化回顾。
- 新增公共层不破坏机械臂、足式、复合、仿真原有学习路径。
- 公式、代码、版本信息经过一次全局复核。
9. 初步时间安排¶
| 阶段 | 工作量估计 | 产出 |
|---|---|---|
| Phase 0 盘点 | 0.5-1 天 | 重复矩阵、引用清单、符号清单 |
| Phase 1 骨架 | 0.5 天 | B00、B99 初稿，总大纲入口 |
| Phase 2 第一批公共章节 | 2-4 天 | B04、B05、B08 |
| Phase 3 第二批公共章节 | 3-5 天 | B02、B03、B06、B07 |
| Phase 4 方向文档瘦身 | 3-6 天 | M/Ch/S/复合章节局部重写 |
| Phase 5 全局审计 | 1-2 天 | 断链、公式、符号、版本、补丁感检查 |
总计建议按 2 周左右 做第一轮完整迁移；如果只做第一批公共层，可控制在 3-5 天。
10. 下一步建议¶
下一步最稳妥的执行顺序是：
- 先完成 Phase 0，生成重复矩阵，明确哪些段落应迁入公共层。
- 新增
B00和B99，让公共基础层先可导航。 - 优先撰写
B04、B05、B08，因为这三类内容重复度高、边界清晰、迁移风险低。 - 对机械臂和足式中对应章节只添加公共基础回顾桥，暂不大删。
- 等公共章节经过公式和符号复核后，再逐步压缩方向文档中的重复基础段落。
这个顺序能在不破坏现有学习体验的前提下，逐步把 05_运动控制 从“多个方向并列堆叠”整理成“公共基础 + 四方向特化”的结构。