Add loaded-standing physics, PPO training, fixed-candidate acceptance, isolated inference, and fail-closed publication. Preserve the original 120-second drift failure and bind the operator-approved exception to the exact candidate and evidence. Include pending Reach training/release infrastructure and archived packages. Leave pre-existing short-worker visualization changes and large generated training artifacts out of this commit.
22 KiB
SkillFactory 统一软硬件描述规范 v2
1. 设计目标与实现边界
以部件的结构、能力和语义端口为契约,不以“腿”“三个关节”“单个足端”作为统一接口的前提。同一格式可描述腿、机械臂、手、夹爪、躯干、颈部、头部、移动底座、纯传感器模块和其他部件;软件通过能力匹配选择可用部件。
已落地: PartSpec v2 / SoftwareSpec v2、JSON Schema、跨文件语义校验、不同部位的设计示例、现有 Go2 单腿描述迁移与回归测试。仓库只保留本规范及两份 v2 Schema,不再并列维护旧版规范。
尚未落地: v2 通用仿真/训练 adapter、描述驱动 launcher、实机驱动、v2 通用冻结发布、跨部件协调训练。第二阶段已有绑定旧 leg-token-v1 的独立 Go2 Reach SkillBundle 流程,见 验收报告,不改变本规范 v2 的运行支持边界。设计模板不是厂家资产;静态契约匹配不证明机械结构可制造、物理模型准确或策略已训练。当前可运行的是既有单腿任务及专用的受载站立实验任务。后者使用独立go2-fl-loaded-stand-v0观测契约和六维安装口传感器,仍不是v2通用adapter;已完成独立PPO首轮训练和物理测试,并在用户明确批准本次耐久漂移偏差后带豁免冻结发布1.0.0;原始30mm漂移门槛并非通过,不代表v2通用能力或实机安全。这些文档仅记录具体实现和运行验收,不是另一份统一软硬件描述规范。
2. 分层模型
PartSpec v2(部件结构、frame、执行器、末端、传感器、时间、安全)
↓ 能力协商、引用和顺序校验
SoftwareSpec v2(要求、容量、语义端口、控制模式、adapter、产物)
↓ adapter 必须显式实现,未实现时拒绝执行
具体后端:Isaac / 其他仿真 / 实机驱动
↓ 各自提供证据
运行验收 → 训练/泛化验收 → 冻结与部署验收
| 层 | 决定的内容 | 不应决定的内容 |
|---|---|---|
| 通用核心 | ID、类型、拓扑、实体引用、单位、frame、数量、语义、安全与版本 | 某厂家命名、固定 DoF、固定足端数量、特定网络维数 |
| 软件 profile | 输入/输出端口、任务目标、支持的能力、特征顺序、归一化、容量 | 擅自修改硬件限位、把缺失传感器当成存在 |
| 后端 adapter | 资产加载、索引映射、张量/设备、坐标转换、控制器和 reset 实现 | 静默支持未验证拓扑、猜测单位、假装已部署 |
part_type 是分类元数据;真正的适配依据是能力。机械臂与腿可以共用 position profile,手可有更多运动关节但更少独立执行器,传感器模块可以没有关节、执行器和末端。允许零 DoF、零末端、多末端和多传感器。
3. 文件、命名与版本规则
- UTF-8 JSON;拒绝重复 key、未知核心字段、非有限数值和不支持的版本。整数字段必须使用整数写法,不接受
2.0或 bool。 - 全局
part_id/software_id使用小写[a-z][a-z0-9_]*;局部实体 ID 允许大小写[A-Za-z][A-Za-z0-9_]*,兼容真实 URDF 命名。各实体集合内部 ID 必须唯一。 - 元数据物理量使用 SI:m、kg、s、rad、N、N·m;四元数 xyzw、右手坐标。角度不得混入 degree;直线关节不得按 rad 解释。
source.root可为机器路径并允许~,相对值按工作目录解释;source.path相对该 root,解析后不可逃逸或越界 symlink。来源许可可显式引用上级仓库文件。- 软件
spec_path/checkpoint.path相对仓库根目录,不允许逃逸或越界 symlink。 extensions只接受 namespaced key,如skillfactory.example。这是注释/来源扩展区,不能藏入未经协商的控制、安全或物理能力;必须影响执行的扩展需制定 profile 和相应校验器。- PartSpec v2、SoftwareSpec v2、旧 LegSpec v1、旧 asset manifest v2、旧 token
FEATURE_SCHEMAv1 分属不同版本域。同为数字 2 不代表是同一种对象。kind必须匹配。 - 同版本拒绝未知字段。核心含义改变需升级 schema;端口顺序/单位/归一化改变需升级
interface.contract_version,不能只改 shape 或软件实现版本后继续加载旧权重。
4. 硬件描述:PartSpec v2
机器格式:schemas/part_spec.v2.schema.json。
4.1 字段分组
| 字段 | 内容与约束 |
|---|---|
schema_version/kind |
固定 2/robot_part |
part_id/part_type |
标识与部位分类;类型含 leg、arm、hand、gripper、torso、neck、head、mobile_base、sensor、other |
description_role |
asset_reference 为真实来源引用;design_template 为未绑定厂家模型的设计模板 |
source |
format/root/path/package、许可、revision 与可选 SHA256;来源格式可为 URDF/USD/MJCF;模板必须 format=design、路径/hash/revision 为 null |
topology |
root body、完整 body 列表、joint 列表、tree/closed_chain 与显式闭链约束 |
frames/root_frame |
body 局部 frame、xyz[m] 与单位四元数;root_frame 必须属于 root body |
attachment |
fixed/floating/external、安装 frame、可选源安装关节与辅助支链;可选源 parent → root 零位变换 |
actuators |
独立执行器声明顺序、受驱动关节、neutral position、支持的 command 模式及尺度/offset/PD gains |
end_effectors |
任意数量、frame、语义 role 与可选接触/gap 方法;不再使用单个 foot_body |
sensors |
任意数量、kind、明确 outputs 语义、frame、目标实体/IDs、更新周期;不是按部位猜测传感器 |
timing |
control_dt_s 必填;physics_dt_s 可为 null;有仿真步长时控制步长必须为其正整数倍 |
safety |
软限位比例、非法命令 reject、超时 hold/zero_effort/disable 与超时阈值;阈值不短于一个控制步 |
scales |
可选长度/已知质量尺度;未知为 null,不得冒充真实测量或厂家值 |
4.2 拓扑、自由度与耦合
每个 joint 描述 id/source_name/type/parent/child/origin/actuation/position_unit/axis/limits_origin/limits/coupling。
- joint
origin是父 body 到零位 joint/child frame 的变换;轴在 joint 局部 frame 表达。revolute/continuous 为 rad、prismatic 为 m;fixed 的单位/轴/限位为 null。 - 当前核心采用标量 joint + floating root表示:球关节等多 DoF 需先拆解为显式坐标或新增专用 profile,不得伪装为一个标量 revolute。
actuation区分 active、passive、coupled、fixed。J 是所有非 fixed 运动关节数;A 是独立执行器数。J≠A 合法,动作按 A 而非 J 排列。- 每个 active joint 恰好一个独立 actuator;passive/coupled/fixed joint 不得被直接驱动。
actuators数组顺序是输出通道顺序,topology.joints中非 fixed 的声明顺序是状态通道顺序;不得按名称重排。 - 耦合显式声明
q_child = multiplier × q_reference + offset,引用同单位的非 fixed joint,依赖图无环。mimic/欠驱动能力可被规范描述,但当前单腿 importer 不支持。 - joints 始终形成覆盖所有 body 的无环 spanning tree。闭链用独立
loop_closureframe 约束表示;不得把循环塞进树。约束可描述不等于当前后端会求解它。 - 有源模型时,几何、质量、惯性、碰撞体和真实限位以来源资产为准;
limits_origin=source表示导入时核对/读取来源,允许未解析限位为 null。declared的运动关节必须有完整限位,且这些模板值不是厂家数据。 - bounded 关节的 position 范围必须 lower<upper;continuous position=null;限速/限 effort 为正。已有完整惯性须由 importer 检验正定,缺失惯性必须保持未知标志,不得估算后称为厂家数据。
4.3 安装、末端和传感器
attachment.mode=fixed表示根与挂载参考固定,不表示冻结内部关节;floating 表示根可动,external 表示位姿由外部系统提供。源切口可以是固定关节,不再要求 mount 一定是受控关节。- frame 的 pose 都相对所属 body。源 parent 零位变换可引用部件外 body;它不是当前世界 pose,也不是已完成的跨部件装配约束。
- 末端 role 可为 support/tool/fingertip/grasp/gaze/sensor_mount/other;腿可多接触点,手可多指尖,躯干可无末端。contact 为 null 时不宣称能算 gap;mesh_distance 必须由相应 adapter 提供,不能用 sphere 近似偷偷替代。
- 传感器输出须明确,如
joint.position、joint.velocity、contact.normal_force、contact.wrench、image.rgb8。camera 不自动等于 RGB,相应 outputs 必须存在;normal_force 不自动等于 wrench。 - 关节传感器的 target 必须列出覆盖的 joints。软件请求的 joint/contact state 要求目标实体被真实声明的传感输出覆盖,不能用另一个部位的传感器凑数。
- 源路径/hash 是来源记录;静态预检不读取原源模型或校验其内容 hash。资产构建/加载仍须单独验证来源、资源、许可、映射、物理参数和派生 hash。
5. 软件描述:SoftwareSpec v2
机器格式:schemas/software_spec.v2.schema.json。
5.1 身份、绑定和能力要求
kind=part_software,身份用 software_id/software_version;当前 v2 格式交付阶段为 design/prototype,trained_skill=false/frozen=false。本版本不提供已训练/冻结发布流程。第二阶段的独立 skillfactory.skillbundle.v1 有自己的证据门槛,不伪装成已获运行支持的 v2 SoftwareSpec。
hardware_bindings 是可替换候选列表,binding_mode=alternatives:每个部件独立满足同一 profile,不能把候选 A 的传感器与候选 B 的执行器合并满足要求。不是同时装配,也不代表已经学会跨部件迁移。
requirements 必须声明:
- 支持的部位、运动 joint 类型、拓扑、挂载模式和耦合能力;
- 必需的执行模式、sensor kinds/outputs、effector roles;
- 每个部件的容量
Jmax/Amax/Emax/Smax(允许 0)。容量覆盖硬件全部相应实体,不只是某个 selector 子集;实际数量超过容量直接拒绝。
不要求所有部位共用一个神经网络或一个固定 D。统一的是描述格式和语义匹配,任务特征布局由 profile 决定。
5.2 语义端口与形状
每个 port 必须描述 name、direction、kind、entity、selector、required、dtype、shape、frame、representation、features、mask、command。
| 维度 | 语义 | 示例 |
|---|---|---|
| B | 批量实例数 | 所有端口的第一维 |
| Jmax | 非 fixed 运动关节槽 | joint_state [B,Jmax,2] |
| Amax | 独立执行器槽 | command [B,Amax,1] |
| Emax | 末端槽 | position goal [B,Emax,3]、pose goal 可定义 7 个特征 |
| Smax | 传感器槽 | RGB [B,Smax,480,640,3] |
| D / 固定 tensor 轴 | profile 的明确整数维度 | features 数目必须与最后一维精确一致 |
- entity 分 part/joint/actuator/end_effector/sensor。实体端口必须使用对应容量轴,不得把手的 Jmax 当成动作 Amax。part 级 context 为
[B,D],不强制实体轴。 - selector 支持 all/ids/role/sensor_kind/sensor_output。按硬件数组顺序过滤,不按 selector.values 重排;不同候选可通过 role 或 all 适配不同名字。
- features 是有序
{name, quantity, unit, normalization};必须声明每个特征的物理语义与归一化。tensor 表示 RGB 等非逐标量数据,features 必须为空;具体布局/编码由命名的 contract 定义。 joint_position/joint_velocity表示按槽 joint type 决定 rad/m、rad/s/m/s;actuator_command表示按 actuator mode 决定单位。软件必须消费对应硬件类型/单位元数据,不能将混合关节槽都按 rad 计算。- normalization 是契约中的明确规则名。示例 identity 为不归一化;command_scale_offset 按 actuator scale/offset 映射。自定义规则必须由对应 adapter 解释;未知规则在执行前拒绝,不得只接受字符串就声称能推理。
- 每个实体数据端口必须引用同 entity/selector 的 bool
[B,capacity]输入 mask。padding 不驱动、不参与损失/概率/路由,adapter 必须屏蔽无效槽中的非有限垃圾值;有效槽非有限值必须拒绝。 required=false允许 selector 选不到实体,adapter 必须返回无效 mask;不是允许把需要的力/图像伪造为零。0 容量实体不得声明端口;纯传感模块可以完全没有 joint/command/effector ports。- 同 shape 不代表兼容:完整特征顺序、quantity、unit、normalization、frame、selector、控制模式和 contract version 都必须匹配;checkpoint 加载还需完整接口/硬件绑定指纹,不可只比维数。
5.3 统一坐标与动态协议
port.frame 可为 part_root/world/entity/none。位置目标不默认是足端,不默认在 world;姿态使用 xyzw;必要的空间速度和 wrench profile 应明确:
- twist 顺序
[vx,vy,vz,wx,wy,wz],分别 m/s、rad/s; - wrench 顺序
[Fx,Fy,Fz,Tx,Ty,Tz],分别 N、N·m,必须注明参考 frame/作用原点; - contact.normal_force 是法向接触力,不能当作含切向摩擦的完整 wrench;控制器 applied/commanded effort 不等于实测电机 effort。
移动根的相对线速度必须包含根角速度产生的 ω×r 项;wrench 换原点必须包含力矩平移项。旧固定支座的直接坐标差分公式不能无条件搬到浮动躯干、头部或底座。
未来 adapter 的每个批次应携带 part_id/instance_ids/control_index/timestamp/description_revision,以区别部件、实例、时刻与描述修订;旧 v1 张量接口未增加这一 envelope。对跨时刻传感器数据,adapter 必须标记有效性/时间差,不能把旧帧当当前状态。
reset 按 profile 声明 indexed_isolated 或 not_applicable;仿真 indexed reset 必须隔离未选实例、清动作历史,空集合 no-op;真实硬件不得把仿真 reset 当成可直接发送的动作。action_history=last_applied 是最后已执行动作,不是最后拟议动作;timeout bootstrap 规则仍由训练 adapter 区分 timeout 与真 termination。
5.4 控制、安全、周期和可执行性
- command 仅允许 actuator output;每个独立 actuator 一个命令来源,重叠命令直接拒绝。
- 模式为 position_pd/position/velocity/effort,必须是目标 actuator 已声明的模式。prismatic 的 effort 为 N,rotary 为 N·m;只有 position_pd 要求显式 PD gains。
- normalized command 使用 dimensionless
[-1,1]执行裁剪,再计算target = offset + scale × clipped_command;position 要再次按软限位裁剪,velocity/effort 受硬限速/限 effort。PPO 仍保留未裁剪采样值的 log-prob。 - physical command 不做隐式尺度映射,明确单位/可选 clip,但仍必须执行硬件安全约束。未解析安全限位、未实现 watchdog、缺失有效传感器、未知转换或控制模式都必须拒绝执行。
- 安全策略是要求,不是已实现证明。hold/zero_effort/disable 都不是所有机构的天然安全状态,需要具体部位/实机验收;不能用模板值宣称满足实机安全。
- runtime.timing 支持 common_control_dt 或 per_part;前者对每个候选核对控制周期,后者由实际选中的部件决定。无需让头部相机和腿共享物理步长;跨部件异步协调不由 alternatives 绑定自动提供。
- runtime.devices/dependencies 是所需/拟支持的环境,不是当前机器探测结果;参考机器配置和已验证运行版本仍另行记录,不编造 GPU/显存最低要求。
- runtime.implementation=available 必须有注册且验收过的 adapter。当前未注册任何 v2 adapter,校验器拒绝假称 available;
--require-runtime也会拒绝仅通过静态协商的 v2 profile。 - 当前 artifact.checkpoint 可为 null 或带 path/hash 的引用。校验只验证文件 hash,不反序列化、不证明权重兼容或收敛;trained/frozen 发布另设里程碑。
6. 多部位示例与运行兼容边界
| 示例 | J / A / E | 关键差异 |
|---|---|---|
configs/parts/go2_fl.json |
3 / 3 / 1 | 从已有真实 Go2 bundle 迁移,保留 fixed 辅助支链和来源 hash |
example_arm.json |
6 / 6 / 1 | 六轴臂,tool role,无默认地面接触传感器 |
example_hand.json |
4 / 2 / 2 | 分支双指、显式耦合、多个 fingertip,动作数少于关节数 |
example_gripper.json |
2 / 1 / 2 | prismatic、m/N、两钳口耦合 |
example_torso.json |
2 / 2 / 0 | 不要求末端 |
example_head.json |
2 / 2 / 1 | gaze + camera/IMU,同一硬件可绑定运动或感知 profile |
example_mobile_base.json |
4 / 4 / 0 | continuous 轮关节、velocity、floating root |
example_sensor.json |
0 / 0 / 0 | external 安装、纯 camera/IMU 模块 |
除 Go2 外,example_* 都是明确的 synthetic design_template,不引用厂家名称、不伪造实测参数、不提供可运行策略。
软件示例:
part_position_control.json:同一可配置关节/执行器端口 contract 绑定腿、臂、手、夹爪、躯干、头部;含可选多末端位置目标。wheel_velocity_control.json:轮式底座独立 velocity profile;不是把腿 position 动作改名。part_rgb_perception.json:头部/纯传感器共用按image.rgb8输出能力选择的感知端口,无 command port。
v2 的新端口不冒充旧 [B,Jmax,25] / [B,1,16] token,不自动加载旧模型。configs/legs/、legs/spec.py 和现有任务/训练 CLI 保留为兼容运行输入与实现,不再附带独立 v1 规范或软件描述。通用校验器只接受 PartSpec/SoftwareSpec v2;旧数据先显式迁移,不静默跨版本。旧专用 Go2 manifest v1 也不被当成通用 PartSpec。
7. 校验与迁移
7.1 静态校验
# 已安装 jsonschema 的 Python 3.12 即可,无需 Kit/Torch
python3 scripts/validate_descriptions.py \
--hardware configs/parts/*.json \
--software configs/software/part_position_control.json \
configs/software/wheel_velocity_control.json \
configs/software/part_rgb_perception.json
# 当前应失败,明确指出 v2 adapter 未实现;不可用静态通过冒充可运行
python3 scripts/validate_descriptions.py \
--software configs/software/part_position_control.json --require-runtime
预检覆盖:schema、唯一 ID、拓扑连通/无环、frame 与目标引用、单位/轴/四元数、耦合关系、独立驱动覆盖、末端/传感器引用、时间关系、逐候选能力协商、容量、特征布局、mask/selector、传感覆盖、命令冲突与可选 checkpoint hash。
**不覆盖:**来源模型内容/许可存在、实际物理参数、碰撞可用性、动态稳定性、传感器分辨率/校准/延迟实测、设备驱动、adapter 坐标/控制行为、制造与安全证明、训练和泛化。语义字符串的执行规则必须由实现后的 adapter 检查。
7.2 从现有单腿迁移
export PYTHONPATH="$PWD/source/SkillFactory${PYTHONPATH:+:$PYTHONPATH}"
LAB=/home/cen/IsaacLab/isaaclab.sh
# 先按 README 提取旧 bundle;然后输出到一个尚不存在的新文件
"$LAB" -p scripts/migrate_leg_description.py \
--bundle assets/generated/legs/go2_fl --output /tmp/go2_fl.part.v2.json
PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 "$LAB" -p -m pytest tests -q
"$LAB" -p -m ruff check source/SkillFactory scripts tests
迁移校验旧 bundle 的资源/派生 hash,保留 actuator 声明顺序、完整 fixed 支链、安装变换、碰撞索引、控制参数和来源记录;不重新认证源厂家模型,也不新增通用后端。迁移生成的 watchdog 策略是 v2 要求,不是旧 runtime 已实现能力。
设计示例由 scripts/examples/generate_part_descriptions.py 确定性生成,可输出到新目录复核;默认拒绝覆盖现有文件。校验/回归实现分别见 scripts/validate_descriptions.py、tests/test_part_contracts.py。
8. 后续扩展规则
增加新部位通常只需新增 PartSpec、选择已有能力/profile,不得复制一个新的“arm-only/hand-only”核心 schema。新任务增加命名端口 contract;真正的新物理类别(柔性结构、多 DoF 未拆解 joint、复杂传动)或新安全/控制语义需显式扩展 profile/核心版本。
装配设计可利用各部件安装 frame 与源 parent 变换,但当前尚未实现 AssemblySpec、跨部件资源冲突、共享传感、控制权仲裁和协调软件。整机组合需显式规定装配图、命名空间、clock 同步和命令所有权,不能把 alternatives 列表当成已经装配完成。
落地顺序:通用部件 importer/实体 adapter → 精确端口/坐标/安全实现与仿真验收 → 跨 DoF/多末端训练及留出评估 → 装配与跨部件协调 → 单独制定冻结产物和实机部署验收。