配置层次
| 文件 | 负责内容 | 不应包含 |
|---|---|---|
| Run | 本次后端、runtime、Scenario、control、plugins 与覆盖 | Registry 搜索策略、共享资产内部结构 |
| Project | Registry、可信根、缓存、离线和部署能力 | 某次实验的场景实例 |
| Component Manifest | release、kind、schema、variant、资源 digest | 使用方的实例位姿 |
| User settings | 明确允许的本机默认项 | 项目必须复现的输入 |
推荐检查顺序
先运行格式与语义验证，再展开规范化结果，随后对关键字段解释来源，最后才生成或验证 Lock。每一步都可输出 JSON，供 CI 或部署系统消费。
bash
fastsim config validate run.yaml --json
fastsim config expand run.yaml
fastsim config explain run.yaml runtime.physics_hz
fastsim config lock run.yaml --output run.lock --json
fastsim config verify-lock run.lock --json
覆盖策略
项目共享事实应放在 Run、Project 或组件中。CLI 与 API 覆盖只适合部署选择、临时诊断或受控试验，并应进入最终 Plan 的 provenance。不要依赖工作目录、导入顺序或机器私有环境变量改变语义。
常见失败类别
- schema 或字段错误：修正作者输入，不应在 Runtime 中兜底。
- component not found：检查 Project 与 Registry index，而不是复制资产到随机目录。
- kind mismatch：确认 URI scheme、Manifest kind 与 Scene 分组一致。
- resource integrity：重新获取受信任资源或更新经过审核的 digest。
- capability mismatch：选择支持该能力的 Provider，或移除不能满足的组件/插件要求。
字段的当前来源与分组见配置参考；一次完整 Run 的形态见Run、ExecutionPlan 与 Lock。