# 接口与运行约束:Go2 FL参考+残差 ## 当前0.4.1:真实GUI与headless分开 [0.4.1实际结果](contact_cycle_sim_gui_v041_result.md):公开`start(..., gui=True)`/CLI `--gui`贯穿approval、监督和认证worker,默认仍headless。独立包`/home/cen/sf-deliveries/go2_fl_contact_cycle_sim-0.4.1/`中`bash demo_gui.sh`真实解析S1开窗;原`demo.sh`和`verify_functional.sh`保留。当前源码GUI/headless S1各六周期原物理/完整性通过;活跃GUI提前关闭2040tick按预期中止,exit2不算完成。 GUI仅新camera/light/UI,原负载及控制/物理/辅助不变;完整后只render保留原场景(最多10分钟),关闭后才完成身份/wait/清理。真实截图和原始录像/原速剪辑在包demo,不是FK动画,Kit约2–3FPS、不保证墙钟1×实时。原0.4.0全部字节/校验保留;0.4.1未重验其完整矩阵/u256或GUI安全停止/超时/极早启动关闭,不继承新资格。所有旧严格失败/accepted_skill=false保持。 --- ## 历史可调用仿真功能版0.4.0 新公开接口/CLI已真实仿真验证,见[API及生命周期](go2_fl_skill_v4_api.md)与[本轮实际结果](contact_cycle_sim_skill_v4_result.md)。`scripts/go2_fl_skill.py`提供start/query/queue/request_stop/wait及authorize/validate/run/status/queue/stop;复用原解析IK/接触/保护,u256仍为可选冻结残差,不是通用adapter。 独立包`/home/cen/sf-deliveries/go2_fl_contact_cycle_sim-0.4.0/`:`bash demo.sh`真实启动S1;`bash verify_functional.sh`串行真实验证20周期/三序列/u256/停止拒绝。每次新有限登记/新grant/新目录;本轮当前登记已消费,不重跑旧例名。 原名义解析20周期、S1/S2/S3各6周期、u256 S1、边界停止/非法拒绝、独立目录公开CLI和外部实时Python队列均通过。目标为固定世界A去/回成对,命令仅A边界生效,不累积或测量重锚。保持原辅助/真值/单seed限制;30mm根XY只诊断,历史accepted_skill=false/严格失败不改写。下列v2/v3及冻结v1约束作为复用/历史继续保留,不取代当前API说明。 --- ## 本轮独立功能版本(先于下列冻结v1合同阅读) 当前优先级已由RootXY精度优化改为完整功能流程。新判据与预算见[功能流程v2](contact_cycle_functional_flow_v2.md),配置`configs/contact_cycle/functional_flow_v2.json`;原v1/严格P1/P2/RootXY配置和失败结果不变。30mm根XY在新功能版本中只记录,旧严格验收仍按原门槛判失败。 新增`legs/contact_cycle_sim/functional_flow_v2.py`只准备独立协议,复用整数时钟/固定A-B-A-B命令;原相位终止和全部安全保护初版不动。本轮复用无autoreset的`EvaluationContactCycleEnv`,两次接缝禁止reset、pose写入、测量落点重锚及拼接。分别报告零残差解析控制与解析参考+原冻结u256确定性残差。 `scripts/audit_cycle_functional_flow.py`是CPU只读审计,输出`trace_functional_passed`,**不授予运行许可、不证明运行期连续性**;全局时钟重启、失败标记及不足3周期均不能通过。实际受监督入口现为`scripts/evaluate_cycle_functional_flow.py`,新绑定在`functional_flow_binding_v2.py`,同步完整记录/接缝核对在`functional_flow_recording_v2.py`。它们使用独立用户批准,不通过旧P1/P2/RootXY授权绕过门禁。 本轮新授权已执行且消费:解析单周期及连续3周期连同监督检查通过,u256单周期通过;u256三周期物理完成但监督器GPU归属检查失败,**原campaign失败保持**。实际36000物理调用/初始化额外0/优化0,无重试;参见[完整结果与启动命令](contact_cycle_functional_flow_v2_result.md)。该次运行后未重试,不追加RootXY试训。 用户新批准的[功能补验v3已实际全部通过](contact_cycle_functional_followup_v3_result.md):同入口`--followup-v3`、新协议/绑定及原检查决策不变的GPU观测;新0物理准备后,先u256原命令3周期完整通过,再六组解析/u256成对3周期全通过,6对初态一致。175500共享调用、39周期、3585.201s、0训练/0重试;GPU/退出清理正常,旧失败仍保留、未查明具体原因。源码/权重/功能阈值/辅助不变,双方功能通过率6/6,不声称学习必要或全域鲁棒。用户另授[持续预算权限](execution_authority.md),后续自主预设护栏并新绑定/独立登记,不再逐次请批、不复用旧grant。原计划与CPU准备为[历史记录](contact_cycle_functional_followup_v3.md)。 ## 原冻结v1契约(历史与复用边界保持) - 任务:`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)。