# 单腿接口与验收 ## 1. 实现范围 ```text LegSpec JSON → URDF 子树/资源/许可 → USD 与映射 → 固定支座环境 → 形态/状态 tokens → 共享 actor/critic → PPO ``` - 已实现真实 Go2 FL、Go1 FL 导入、CUDA 批量仿真、indexed reset、目标条件共享 PPO 短更新。 - 支持独立 bounded revolute 树、显式辅助 fixed 支链、一个足端、sphere/box 间隙探针;mimic、prismatic/continuous、闭链、柔性结构和 mesh 足底近似明确不支持。 - **未实现** ModSkill 式学习 latent、跨部件协调、冻结 SkillBundle、高层调用及真实留出形态泛化。人工 goal、URMA 内部 action intent、保存 checkpoint 都不等于已学得可复用 Skill。 - Go2/Go1 都是 3 DoF;生成的 1/2/4 DoF 夹具验证接口,不代替真实不同 DoF 或迁移实验。 ## 2. 资产与物理契约 公共入口:`SkillFactory.legs.LegSpec` / `JointSpec`、`legs.urdf.extract_leg`、`legs.spec.load_bundle`。示例 `configs/legs/{go2_fl,go1_fl}.json`。 | 声明 | 含义 | | --- | --- | | source_root / urdf / package_name / license_file / license_id | 来源、资源解析及许可 | | mount_joint / auxiliary_root_joints | 切口与保留支链;辅助 roots 必须 fixed 且共用源 parent | | joints | 受控关节的**声明顺序**、q_default、action_scale、Kp/Kd | | foot_body / foot_collision_index | 独立传感 body 与用于 gap 的碰撞体 | | soft_limit_factor / physics_dt / decimation | 软限位与物理/控制时间步 | 提取按树而非名称前缀;全部 moving joints 必须受控,保留足端/rotor/固定碰撞辅助。合成 `anchor_base` 无碰撞、质量 1 kg、惯性对角 0.001 kg·m²;固定安装座,不冻结 hip。anchor frame 为安装关节零位 frame,源 parent 到 anchor 的变换保存在 `manifest.mount`,供未来装配使用。 输出:`leg.urdf`、asset manifest v2、完整资源、`LICENSE`、分层 USD、`conversion.json`。加载校验 URDF/资源/许可 hash、执行顺序、转换 manifest hash、独立 body/joint 映射、固定支座及层依赖;拒绝逃逸路径、输出覆盖源目录及越界 symlink。改描述/重提取后必须重转换,资产目录整体迁移。 真实 Unitree 资产保留 BSD-3-Clause 许可,不修改原文件。有源惯性保留完整 tensor 并检验正定;Go2 `FL_calflower/FL_calflower1` 缺少惯性,PhysX 实测估算质量约 0.0247086/0.0226430 kg,不能冒充厂家数据。质量尺度为源已知惯性质量和,排除 anchor 和未知估算质量;有效导入 body masses 随运行报告保存。 默认显式 Ideal PD,示例 Kp=25、Kd=0.5,导入器 drive 关闭;限矩/限速取 URDF,目标为 `q_default + action_scale * clamp(action,-1,1)`,再按软范围裁剪。Go2 默认 `[0,0.8,-1.5]` rad、scale=0.25;限矩 `[23.7,23.7,45.43]` N·m、限速 `[30.1,30.1,15.7]` rad/s。物理 0.002 s / 控制 0.01 s。 新任务用本地 `legs/resources/ground.usda`(z=0、静/动摩擦 0.8/0.6、恢复系数 0);旧基准地面保持原配置。足端显式启用 contact reporter;运行入口验证 ground collider 和传感器唯一映射。 ## 3. 通用任务 `SkillFactory-LegSkill-v0` **Kit 启动后**构造 `LegEnvCfg(bundle_dir=..., max_joints=8)` 并 `gym.make(...)`。默认悬空高度为保守足端路径长度 +0.1 m;ReachCommand 对实际动作范围内姿态做 FK,生成运动学可达的足端 link 位置目标。reward 为归一化 tracking、effort 与 action-rate 惩罚,不保证目标动态可行或已学到步态。 `obs['policy']` 字典:浮点 CUDA float32、mask bool;anchor 坐标、米/弧度/SI;四元数 **xyzw**、世界 z 向上。完整字段顺序/归一化由 `legs.tokens.FEATURE_SCHEMA` 定义,并存入 checkpoint。 | 字段 | 形状 | | --- | --- | | joint_description / joint_observation / joint_mask | `[B,Jmax,25]` / `[B,Jmax,3]` / `[B,Jmax]` | | effector_description / effector_observation / effector_mask | `[B,1,16]` / `[B,1,11]` / `[B,1]` | | context / goal | `[B,10]` / `[B,3]` | - joint description 含 nominal 轴/位置、范围/控制规格、source child mass、COM 惯性及偏移;COM/inertia 转到 anchor nominal frame,**不做 fixed-subtree 复合惯性聚合**。 - joint observation:`(q-q_nominal)/scale`、`dq/limit`、最后已施加动作(ActionManager.action)。 - effector:link 原点位置/线速度、ground-filtered **法向**力、接触标志(>1 N)、选定碰撞体 gap。不是切向摩擦力、实测电机扭矩或六维 wrench;其他碰撞体的全脚掌最小 gap 未实现。 - context 保留重力、dt、地面相对高度、长度/已知质量、限矩对重力力矩比、绝对限速、缺失惯性标志,避免归一化擦掉物理差异。 - 当前必需传感器,无噪声/DR;未来随机化物理属性必须同步描述,不能沿用静态缓存。 `mdp.state(env).snapshot()` 返回新 token 视图;跨 step/reset 保存须 clone。`state(env).actions([B,Jmax])` 去 padding 后再调用 `env.step([B,N])`;**Gym action space 是实际 N**。虚拟槽不驱动,也不参与路由/log-prob/entropy/梯度。 `reset(env_ids=...)` 支持全量、索引、空集合 no-op;拒绝负/越界/重复/非整数索引及空 reset reseed。复位清理目标、动作/历史、episode;不重建 stage、不推进物理时间,不改变未选实例。非法原生动作在 ActionManager 改历史前拒绝。timeout 使用 reset 前的 terminal tokens bootstrap,真 termination 不 bootstrap。 ## 4. 训练与失败语义 `LegActorCritic`:静态描述 MLP 的逐 latent 特征 softmax 路由动态状态、共享核心、共享逐关节高斯 decoder。不是大型 Transformer 或完整 ModSkill 复现。 不同拓扑按独立同构 worker 采样,只在 PPO 层合并,不能认为 `replicate_physics=True` 支持任意拓扑混装。各资产等量采样、共用采样权重/optimizer,必须同 physics/control dt;device 显式传给 worker。保存未裁剪动作的 log-prob,实际执行再裁剪。更新前检验概率一致性;GAE/旧 rollout 梯度分离,拒绝空/非有限输入。 当前每轮重启 Kit、CPU 文件交换,**仅适合短测试,不适合直接长训或吞吐结论**。checkpoint 仍标 `trained_skill=false`。 运行报告先写 `passed=false/status=running`,环境成功关闭后才提交成功;JSON 原子替换并拒绝 NaN/Inf。关闭异常/子进程失败/critical log 均保留非零退出码,检查 error/fatal/contact buffer overflow,不能只看进程退出 0。优化按字段读取观测,不缓存跨 reset 状态;FK 常量与 box 投影复用/向量化。 ## 5. 保留基准 `SkillFactory-SingleLegAnchor-Go2-v0` 接口不变:CUDA float32 actions `[B,3]`,policy `[B,19]`: | 切片 | 字段 | | --- | --- | | 0:3 / 3:6 | q-q_default [rad] / dq [rad/s] | | 6:9 / 9:12 | foot link 位置 [m] / 线速度 [m/s],anchor frame | | 12:15 / 15:16 | ground 法向力 [N] / contact float 0/1 | | 16:19 | ActionManager.prev_action(旧接口历史语义,区别于新任务) | 旧默认支座高度 0.344598 m、足球 r=0.022 m / local offset=(-0.002,0,0);默认 timeout 10 s,验收禁用。旧空 reset 在验证调用端做 no-op;不要假设底层普通 ManagerBasedRLEnv 支持空索引。诊断 `single_leg_anchor.mdp.observations.diagnostics` 包含 q/dq/目标、限幅前后命令 torque、gap、anchor pose、`[B,5,1,3]` 历史;torque 非实测、`reaction_wrench=None/valid=False`。 ## 6. 验收证据与限制 **第一周历史完整验收**:`logs/week1_anchor/acceptance/result.json`,`passed=true/milestone_complete=true`;原 Go2 URDF SHA256 `7d19fe48e2e689ee1a032ab99f2a4a8b671d87e73de48d3e65811682a5b48b9e`,源提交 `daadf41ee9afce8f90fdc09a98506012691fa122`。 | 项目 | 实测 | 保留阈值 | | --- | --- | --- | | B=1/16/64 接口 | `[B,19]` CUDA、顺序/有限性通过 | shape/order/finite 匹配 | | 悬空 60 s + 2 s warmup,0.1 rad / 0.5 Hz | RMS `[0.043313,0.017097,0.009654]` rad,根漂移/转角 0 | RMS≤0.10,根≤1e-4 m/1e-3 rad,硬限位容差0.01 rad、torque不越界 | | 20 次抬脚/压地 | 离地 0 N;最小稳定平均 Fz 31.3321 N | gap≥1 cm/力<0.1 N,压地>1 N | | 接触响应/穿透 | 延迟0控制周期、最大1.40e-6 m | ≤1周期 / ≤5 mm | | 独立1 kg小球标定 | 9.810026 N | m·g误差≤20% | | 耐久 | 64×600 s、60,000控制/300,000物理步 | 完整时长、无非有限/意外reset/限位异常 | | reset隔离 | 1,334操作=1,001非空+333no-op;误差0、prim数2384不变 | ≥1000真reset,q/dq≤1e-5、未选≤1e-6、历史清零、不重建 | | 资源 | device used 3,814,981,632 B前后不变 | warmup后增长≤5% | 历史墙钟 576.748 s(约6,658环境控制步/s)、reset均值/最大1.785/4.620 ms;没有墙钟实时门槛。显存包含 Warp/PhysX,不能只报 Torch 分配。固定支座承担载荷,足端力**不等于腿重量**。 **本次代码复验**放在 `logs/code_review/`,不覆盖历史验收: - 全部定向测试 **43 passed**(含旧任务 B=1/16/64 Kit 集成),全仓库 Ruff / `git diff --check` 通过。 - `go2_64`、`go1_contact_64`、`fixture2_16`:原生/token动作、快照一致性、任意轴/box、索引/空reset与接触复验通过。 - `train_mixed_smoke`:三组各16环境、32步、1次共享PPO,概率与checkpoint一致性通过;`trained_skill=false`。 - `anchor_debug`:缩短的旧full套件通过,明确 `milestone_complete=false`;最终运行日志无error/fatal/buffer overflow。 缩短时长的通过不等于重做600 s验收;生成夹具或一次 PPO 更新不证明真实泛化/收敛。 生成缓存与证据不入库,迁移机器需重建复验。后续顺序:常驻采样与训练/留出评估 → reference/goal-to-latent 学习 → 冻结低层与高层复用 → 单独评估移动基座/整机协调。 研究参考:[URMA](https://arxiv.org/html/2409.06366v2)、[ModSkill](https://arxiv.org/html/2502.14140v1)。本项目是固定支座单腿工程改编,不是原论文全身模仿或零样本迁移复现。