配置职责边界
| 文件 | 负责内容 | 不应包含 |
|---|---|---|
| Run | 本次后端、runtime、Scenario、control、plugins 与覆盖 | Registry 搜索策略、共享资产内部结构 |
| Project | Registry、可信根、缓存、离线和部署能力 | 某次实验的场景实例 |
| Component Manifest | release、kind、schema、variant、资源 digest | 使用方的实例位姿 |
| User settings | 明确允许的本机默认项 | 项目必须复现的输入 |
编译器按上述职责合并配置并记录来源。改变运行语义的值必须进入 Run、Project 或 Component；User settings 只能提供明确允许的本机偏好。
从声明到可重复检查
先运行格式与语义验证，再展开规范化结果，随后对关键字段解释来源，最后才生成或验证 Lock。每一步都可输出 JSON，供 CI 或部署系统消费。
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。
从最小 Run 开始。 当前仓库的 quickstart 使用 fastsim/2 schema、PyBullet、显式 runtime 时钟和 seed，并在 Scene 中实例化一个组件：
schema: fastsim/2
name: quickstart
backend: pybullet
runtime:
launch_profile: headless
physics_hz: 60
control_hz: 30
seed: 7
scenario:
scene:
objects:
cube:
use: object://fastsim/quickstart-cube
pose:
xyz_m: [0.0, 0.0, 0.5]
quat_xyzw: [0.0, 0.0, 0.0, 1.0]
这里的 use 不是相对资产路径；它要求 Project/Registry 能解析对应组件。Run 只声明本次实例位置，组件 Manifest 才拥有几何资源与 backend variants。
接下来建立固定的五步检查循环。
Validate：先解决作者错误。 对每次修改先运行 validate，并在 CI 使用 JSON 与退出码。此时应修复 unknown field、类型、枚举、跨字段关系等问题；不要启动 Provider 验证 YAML 是否拼对。
Expand：确认规范化形态。 Expand 用于观察默认值、简写展开和合并后的结构。重点检查 backend、runtime rate、Scenario 实体、插件实例和 control precedence 是否与意图一致。
Explain：追踪关键值来源。 对可能受默认、Project 或覆盖影响的字段运行 explain。把 explain 结果保存到审查证据中，比在 README 中描述“通常取这个值”更可靠。
Lock：固定批准的输入。 准备正式运行时生成 Lock，再立即 verify。把 Run、Lock、Plan digest、Core/插件发行版本放进同一部署清单；任何一个发生变化都应重新评审。
Run：最后才打开后端。 只有无后端检查通过后才执行 Run。后端启动失败应被分类为 Provider、资源或运行时能力问题，不要回头用未知字段规避 Compiler。
Project、设置与插件配置
Project 负责所有开发者和部署都必须共享的 Registry、可信根、缓存/离线策略；用户设置只负责明确允许的本机偏好，例如输出根、CLI 展示或 worker 数。backend、seed、physics rate、插件和实体不能藏进用户设置，因为它们会改变运行语义。
如果一份 Run 在另一台机器解析成不同组件，首先比较 Project 与 Lock，而不是复制对方的整个环境变量集合。
插件配置的检查重点。 每个实例需要稳定实例名、Plugin ID 和插件私有配置；需要实体时使用 binding，需要服务隔离时使用 access；多个控制源时声明完整 precedence。Compiler 能验证的合同应在此阶段失败，而不是等插件 start 后自己猜机器人。
变更审查与完成标准
不要只比较 YAML 文本。一次可靠审查应同时查看：作者输入 diff、expand 后结构 diff、explain 来源变化、组件/资源摘要变化、插件与 capability 变化、最终 Plan/Lock digest。格式重排可能没有语义变化，一行版本约束却可能替换整个资产。
配置工作在以下条件同时满足时才算完成：validate 成功；关键值来源可解释；组件和插件均解析到预期版本；当前 Provider 能力满足要求；Lock 可验证；Run 的结构化启动信息包含预期 plan digest。下一步可进入组织组件与资产或直接查询配置参考。