9fe9d27865
Consolidate next-stage docs, archive superseded narratives, and preserve frozen document inputs. Retain invalid P2 pairs, partial RootXY training, failed attempts and nonselectable checkpoints as explicit limitations. Include supervised evaluation/training, desktop GPU admission, bounded evidence and atomic-publication monitor repairs with CPU regressions. Ignore local dotenv configuration. Validation: 1403 passed, 6 skipped for contact-cycle and related contracts/CLI tests. Full-suite legacy ABI and registration tests require Python 3.12/Torch 2.10/pxr; no runtime checks relaxed. No new physical run or accepted skill.
83 lines
6.5 KiB
Markdown
83 lines
6.5 KiB
Markdown
# 接口与运行约束: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)。
|