组件解析模型
Project 定义解析环境。 项目根目录中的 .fastsim/project.yaml 声明 Registry、可信资源根、缓存、离线模式、已安装包发现与部署能力上限。CLI 从 Run 所在目录向父目录寻找这个准确文件，不递归扫描整个工作区。
Project 回答“允许从哪里解析”，Run 回答“本次选择什么”。两者分开后，同一个 Run 可以在受控部署环境中复现，而无需嵌入机器私有路径。
Registry 映射稳定身份。 Registry index 将 component identity 映射到版本化 Manifest release，并明确默认 stable 版本。没有版本的 URI 只使用 Registry 指定的 stable；相同身份和版本出现不同内容时必须失败，不能采用“先找到的文件”。
Manifest 描述一个 release。 Manifest 声明组件 kind、参数 schema、语义信息、后端 variants、资源摘要和能力需求。编译器校验 URI scheme 与放置位置，例如 robot 不能作为普通 object 静默加载。
常见 kind 包括 environment、object、articulation、robot、deformable、fluid、sensor、light、scenario 与 plugin。具体后端资源属于 variant，不改变组件稳定身份。
资源必须保留来源。 资源可以来自项目 Registry、固定远程 Registry 或已安装包。进入 Plan 之前必须落到受信任根或受控缓存，并记录 release、variant 和 digest。运行时不重新选择资源。
这套分工带来几项直接收益：
- 项目作者写稳定 URI，不承担目录布局与版本选择细节。
- 资产维护者可以增加后端 variant，而不修改使用方 Run。
- 编译器可以在启动物理引擎前给出冲突、kind mismatch 和资源完整性诊断。
- Lock 能准确记录解析结果。
实际文件组织见组织组件与资产。
解析流程
解析从 Run 所在 Project 开始。Project 给出允许使用的 Registry Index、可信本地根、远程 Registry 约束、缓存与离线策略；Index 把稳定 URI 映射到一个或多个 release；release Manifest 再给出 kind、版本、语义、variant 与资源。
Compiler 不应递归扫描整个目录猜测组件，也不应因为某个 Python 包碰巧可导入就改变选择。显式索引让解析顺序、重复 ID、版本冲突和来源都可检查。
Release、目录与后端 variant
Component release 的不变量。 一个 release 表示一个可识别、可复用的组件版本。它至少需要稳定 ID、语义版本、kind 和资源描述。机器人通常还包含 joint/link/frame、控制 group 与单位等语义；sensor 包含数据类型与 frame 关系；不同后端资源放在 variants 中。
同一 release 的不同 variant 可以使用 USD、URDF 或 MJCF，但必须尽可能保持稳定实体语义。若 joint 身份、坐标约定或关键物理含义改变，应发布新 release，而不是让后端 variant 暗中改变上层合同。
Registry 不等于文件目录。 Registry 是“哪些身份和版本可被解析”的索引合同，目录只是存储实现。组件可以来自项目仓库、独立资产仓库、已安装发行包或固定摘要的远程 Index；只要进入同一解析协议，Run 都使用相同 URI。
因此，把新 URDF 放进 assets/ 并不会自动使它成为组件。需要为源资产保留 provenance，生成必要派生资源，编写 Manifest，并把 release 登记到允许的 Index。
版本与后端 variant 分两步选择。 版本选择先满足 Run/Project 的约束，再从准确 release 中选择当前 backend 的 variant；通用 * 只能在合同允许时作为回退。Variant 选择不能反过来改变 Run 的 backend，也不能悄悄下载未锁定的“最新模型”。
如果组件在 Isaac Lab 有相机能力、在 PyBullet 没有，相应差异需要进入 capability 结果。上层应用据此选择可用路径或在编译阶段失败，不能把空数组伪装成有效传感器输出。
完整性检查与失败处理
资源解析完成后仍需要确认：最终路径位于可信根或受控缓存、文件类型和大小符合约束、符号链接策略未越界、内容摘要匹配。派生 USD 或简化 mesh 应与 vendor 源分开存放，并记录生成工具、参数和源摘要。
准备正式部署时，Lock 同时固定 release、variant、资源摘要和 Plan digest。仅固定 Registry URL 不足以复现，因为远端内容可能在相同地址被替换。
| 错误 | 含义 | 正确修复 |
|---|---|---|
| component not found | 允许的 Index 中没有匹配 ID/版本 | 检查 Project Registry 与 release 登记 |
| duplicate/conflict | 多个来源提供冲突身份 | 明确优先级或移除不可信来源 |
| kind mismatch | URI/Manifest kind 与 Scene 分组不一致 | 修正组件分类或 Scene 引用 |
| variant unavailable | 该 release 没有当前 backend 的实现 | 增加经过验证的 variant 或换组件 |
| digest mismatch | 内容与声明不一致 | 恢复可信文件或发布新 release |
下一步阅读Scenario 与 Scene了解组件如何被实例化，或按组织组件与资产完成一个可维护的项目结构。