# 接口与运行约束:Go2 FL参考+残差 ## 当前契约 - 任务:`SkillFactory-Go2FL-ContactCycleSim-v1`。 - 特征:`contact-cycle-sim-truth-residual-46-v1`;46D、float32、有限值,不能载入旧32D策略。 - 名义9秒周期:承重3s、卸载1s、抬腿0.6s、摆动1.4s、落地0.8s、重新承重2.2s。 - 500Hz物理/失败检查,100Hz控制。默认位移`[0.025,0.02,0]`m,净空0.05m+0.01m拱高。 - 浮动根、3kg合成载荷/传感载体、真实接触/六维测力;当前有效系统质量约5.388kg,W指有效系统重量,不仅是3kg载荷重量。保留有界横向/转动辅助,竖直guide力必须为0。不是固定根,也不是无辅助平衡。 - 当前使用仿真真值,名义任务不接受旧课程采样器、stand-only、扰动或传感/执行器随机化的静默混入。 ## 观察与动作 | 观察索引 | 含义 | |---|---| | 0–31 | 原传感/命令32D,包括上一步完整归一化关节动作 | | 32–34 | root相对命令挂载点的位置误差,世界系m | | 35–37 | root相对命令的线速度误差,世界系m/s | | 38 / 39 | 真实地面法向力Fn(N)/真实足端gap(m) | | 40–42 | 下一控制步的归一化参考动作 | | 43–45 | 上一控制步夹紧后的请求残差,不是投影后的实际残差 | 参考由足端目标、阻尼IK和Jacobian载荷补偿生成,仅在reset或控制边界推进,不能因读取观察而推进。3维残差请求先夹到±1,每关节对应±0.05rad;合成目标再投影到原关节范围,投影只能缩小实际残差。 必须分别记录`reference_used_normalized`、`reference_next_normalized`、`residual_request_normalized`、`effective_residual_rad`和实际关节目标。PPO概率针对采样残差latent,不针对合成后的绝对关节动作。随机策略与确定性均值策略要明确区分。 checkpoint为`skillfactory.contact-cycle-sim-residual-ppo-checkpoint.v1`。原参考/零初始化actor成功不算学习;本轮已训练u256身份见[当前进度](current_status.md)。原task objective之外保留root位置/速度和残差成本,具体尺度以绑定配置为准,不能为了新实验原地改旧配置。 ## 不可绕过的门禁 - 接触获取:200ms内达到至少0.5W并持续10ms、gap≤0.5mm;失败必须终止。 - 离地检测:on=1mm、off=0.5mm、dwell=10ms;保持真实起始阶段和首次失败来源。 - timeout bootstrap用reset前的终端观察;真实失败bootstrap为0;禁止跨reset串接回合。 - 有限性、关节/力矩/速度约束、辅助力边界及物理失败检查保持启用。非有限动作必须在污染动作历史前拒绝。 - 使用SI单位;项目对外四元数约定xyzw,与后端不同约定要显式转换。力/力矩坐标系与作用点必须明确,统一经唯一COM外力合成入口,不能重复叠加r×F或把辅助力冒充足端接触力。 - 功能门槛是开发阶段形成的判据,不是独立验收;不得删失败、放宽门槛或用autoreset后的轨迹补成功。 ## 实现入口 | 用途 | 路径(仓库根目录相对路径) | |---|---| | 参考、模型、PPO、预算协议 | `source/SkillFactory/SkillFactory/legs/contact_cycle_sim/` | | 仿真环境、动作、记录 | `source/SkillFactory/SkillFactory/tasks/manager_based/contact_cycle_sim/` | | 任务/功能/训练配置 | `configs/contact_cycle/simulation_residual_v1.json`、`simulation_functional_v1.json`、`sim_training_v1.json` | | 训练器(不是回放器) | `scripts/train_cycle_sim_residual.py` | | 非优化接口/物理探针 | `scripts/verify_cycle_sim_residual.py`、`verify_cycle_sim_learning_runtime.py` | | 功能审计 / Kit监督 | `scripts/audit_contact_cycle_functional.py` / `scripts/supervise_sim.py` | 旧`train_contact_cycle.py`仍属于32D路径;不要用于46D候选。已实现冻结回放`scripts/replay_cycle_sim_residual.py`,P1/P2准备与评估为`prepare_cycle_sim_binding.py`/`evaluate_cycle_sim_residual.py`。RootXY独立入口`train_cycle_sim_rootxy_v2.py`,同46D观察但独立task/checkpoint身份;仅XY奖励尺度变化,详见[配方](contact_cycle_rootxy_v2_plan.md)。新任务不得借用旧grant或用不可选取u64替换冻结u256。 ## 安全运行 仓库根目录下执行。只读复核已有训练,不启动Kit: ```sh python3 logs/contact_cycle/sim_residual_training_v1/verify_delivery.py ``` 本机CPU测试解释器:`/home/cen/miniconda3/envs/linker_sim_isaac/bin/python`(Python3.11/Torch2.7);不要用缺Torch的系统Python跑学习测试。用以下文件映射跳过顶层Kit任务注册,**仅供CPU测试,不可用于运行绑定**: ```sh CUDA_VISIBLE_DEVICES='' PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 \ /home/cen/miniconda3/envs/linker_sim_isaac/bin/python - <<'PY' import importlib.util, sys from pathlib import Path root = Path.cwd() spec = importlib.util.spec_from_file_location( 'SkillFactory', root / 'source/SkillFactory/SkillFactory/__init__.py', submodule_search_locations=[str(root / 'source/SkillFactory/SkillFactory')]) sys.modules['SkillFactory'] = importlib.util.module_from_spec(spec) sys.path.insert(0, str(root / 'scripts')) import pytest targets = [str(p) for p in sorted((root / 'tests').glob('test_contact_cycle*.py'))] raise SystemExit(pytest.main(['-q', *targets])) PY ``` 上面只跑接触周期主线。全仓旧发布/ABI测试要求Python3.12+Torch2.10.0;任务注册另需pxr/Isaac运行依赖,不应在此3.11/Torch2.7环境期待全套通过,也不能放宽冻结包版本检查来凑通过。不少CPU回归读取本机冻结快照/安装文件;缺少时失败或显式skip不等于新机器获得资格。Isaac运行使用固定`/home/cen/IsaacLab`、`/home/cen/isaacsim-6.0.1`及RTX5080,不把CPU测试版本当实际Kit依赖版本。 默认测试中跳过的PhysX包装不算已执行物理验证。不要运行根目录`pytest`,它可能收集`logs/`中的归档测试;不要在根目录执行`uv sync`或修改外部Isaac Lab/Unitree资源。 当前RootXY和P1/P2必须使用各自认证受监督入口,不得用通用`supervise_sim.py`替代授权/绑定/归属检查。监督器使用`/usr/bin/python3.12`,真实worker在认证FD交接后加载AppLauncher。不得覆盖原证据、杀无关进程或把工具attention当作卡死。采用同一boot绝对`CLOCK_BOOTTIME`截止、rollout预扣、成功后提交;中断不退款,旧grant/目录不复用。配置准备不等于批准运行。详情见[启动合同](contact_cycle_rootxy_v2_launch.md)和[评估监控](contact_cycle_native_monitor_v3.md)。