项目结构与组件职责
project/
├── .fastsim/project.yaml # Registry 与可信根
├── runs/ # 本次应用声明
├── scenarios/ # 可复用 Scenario 组件
├── components/
│ ├── index.yaml # Registry index
│ ├── robots/ # 版本化 Manifest
│ ├── objects/
│ └── sensors/
└── assets/ # Manifest 引用的受控资源
目录名不是自动发现协议；真正的解析入口仍是 Project 中显式登记的 Registry index。
选择正确的 kind。 environment 表示场景底座；object 表示普通刚体；articulation 表示非机器人铰接物；robot 是具备控制语义的 articulation 特化；sensor、light、deformable 与 fluid 具有各自明确合同。不要为了复用一段加载代码而把所有内容伪装成 object 或 robot。
后端 variants。 同一组件可以为 isaaclab、mujoco、pybullet 或通用 * 提供不同资源。Variant 应保持组件稳定语义与 frame/joint 身份，并准确声明能力差异；它不能改变 Run 选择的后端。
资源完整性。 USD、URDF、MJCF、mesh、纹理与参数文件均应作为 Manifest 资源记录来源与摘要。Vendor 源资产应保留，转换后的 USD 或简化 mesh 放入新的版本化派生目录，并在 Manifest 中记录 provenance。
实例覆盖。 初始 pose、实例名称与本次参数放在 Scenario。共享几何、joint 语义和标准 frame 放在组件 release。若覆盖改变组件身份或物理含义，应发布新 release，而不是把长期修复藏在单个 Run 中。
概念关系见Project、Registry 与 Component及Scenario 与 Scene。
一条可靠的资产接入路径
保留原始来源。 把 vendor URDF、mesh、纹理和说明视为只读源资产，记录来源位置、获取时间、许可证与内容摘要。不要为了适配仿真器直接覆盖原文件；修复或转换结果进入单独的派生版本目录。
检查模型语义。 在转换前确认单位、up axis、关节类型与限位、collision/visual、惯量、mimic、材质、传感器 frame 和末端执行器 frame。视觉上“看起来正确”不能替代 joint 名称、坐标和质量属性检查。
生成后端资源。 按需要生成 Isaac Lab USD、MuJoCo MJCF 或 PyBullet 使用的 URDF 等 variant。每个转换记录工具版本、参数和源摘要；同一 release 的各 variant 保持稳定 joint/link/frame 身份。
编写 Component Manifest。 Manifest 使用准确 kind，声明稳定语义、后端 variants、资源 format/role 与 digest。机器人还应按公共合同组织控制 groups、逐轴单位和 frame；相机等传感器需要明确父 frame 与数据能力。
登记 Registry release。 将 Manifest 加入明确的 Index，再从 Project 引用该 Index。验证 URI 能在离线/在线策略下解析，重复 ID 与版本冲突能够被发现，资源路径不能逃逸可信根。
用最小 Scenario 实例化。 先创建只包含该组件的最小 Run，检查 compile、catalog 和稳定身份，再逐步增加其他对象、传感器和插件。这样能区分组件自身问题与复杂场景组合问题。
验证组件语义与多后端一致性
| kind | 关键语义 | 最小验证 |
|---|---|---|
| environment | 世界基座、碰撞、静态 frame | 可加载、尺度/轴正确、无意外动态体 |
| object | pose、质量、碰撞和抓取相关几何 | 稳定落体、碰撞与视觉一致 |
| articulation | joint、limit、link/frame 与驱动 | catalog 顺序稳定、限位有效 |
| robot | articulation 加控制 group、末端和传感器 frame | targets 与状态使用稳定 joint ID |
| sensor | parent frame、数据类型、频率和校准 | 时间、frame、shape 与 capability 正确 |
| deformable/fluid | Provider 能力与专用物理参数 | 缺能力时明确拒绝，不静默降级 |
多后端一致性不是像素一致。 不同物理引擎无法保证逐帧完全相同，但组件身份、joint/frame 名称、单位、控制 group 和能力声明必须一致。应分别记录每个 Provider 的加载、catalog、基本动力学和关闭证据；尚未运行的真实后端标记为未验证，而不是根据文件存在推断通过。
派生资产的版本规则。 转换工具、源文件、比例、碰撞简化或关节修复任一影响物理/语义时，生成新派生版本并更新摘要。保持 Manifest 可以追溯到源资产和配方；不要让 latest.usd 成为正式 Run 的唯一依据。
常见反模式
- 在 Run 中直接引用某台机器的绝对 USD 路径；
- 将 robot 当作 object 只因为某个后端能加载；
- 不声明 frame/单位，让插件猜坐标；
- 只验证截图，不检查 catalog、joint limit 和控制 target；
- 覆盖 vendor URDF 后无法说明改了什么；
- 一个 variant 修复了 joint 名，其他后端仍使用旧身份。