# SkillFactory 统一软硬件描述规范 v2 ## 1. 设计目标与实现边界 以**部件的结构、能力和语义端口**为契约,不以“腿”“三个关节”“单个足端”作为统一接口的前提。同一格式可描述腿、机械臂、手、夹爪、躯干、颈部、头部、移动底座、纯传感器模块和其他部件;软件通过能力匹配选择可用部件。 **已落地:** PartSpec v2 / SoftwareSpec v2、JSON Schema、跨文件语义校验、不同部位的设计示例、现有 Go2 单腿描述迁移与回归测试。仓库只保留本规范及两份 v2 Schema,不再并列维护旧版规范。 **尚未落地:** v2 通用仿真/训练 adapter、描述驱动 launcher、实机驱动、v2 通用冻结发布、跨部件协调训练。设计模板不是厂家资产;静态契约匹配不证明机械结构可制造、物理模型准确或策略已训练。当前专用单腿链路的进度见[当前状态](current_status.md),参考+学习残差的46D契约见[运行接口](contact_cycle_runtime.md),两者均不代表v2通用adapter已实现。旧Reach绑定leg-token-v1;受载站立使用独立观测及六维测力,已[带候选专属漂移豁免发布1.0.0](loaded_stand_release_1_0_0.md),原始30mm门槛并非通过。旧实现/验收详述已归入[历史资料](README.md#历史资料),不作为另一份统一规范。 ## 2. 分层模型 ```text 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_SCHEMA` v1 分属不同版本域。**同为数字 2 不代表是同一种对象。** `kind` 必须匹配。 - 同版本拒绝未知字段。核心含义改变需升级 schema;端口顺序/单位/归一化改变需升级 `interface.contract_version`,不能只改 shape 或软件实现版本后继续加载旧权重。 ## 4. 硬件描述:PartSpec v2 机器格式:[`schemas/part_spec.v2.schema.json`](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_closure` frame 约束表示;不得把循环塞进树。约束可描述不等于当前后端会求解它。 - 有源模型时,几何、质量、惯性、碰撞体和真实限位以来源资产为准;`limits_origin=source` 表示导入时核对/读取来源,允许未解析限位为 null。`declared` 的运动关节必须有完整限位,且这些模板值不是厂家数据。 - bounded 关节的 position 范围必须 lower