# Public Contracts

本目录是跨团队共享的数据契约，修改权限和版本规则见 `docs/governance/ownership.md`。

## 校验顺序

1. 根据 `kind` 使用本目录对应的公共 JSON Schema 校验 YAML/JSON 文件。
2. `FunctionConfig` 再使用 `domains/<domain>/schemas/function-parameters.schema.json` 校验领域参数。
3. 调用领域 Validator 做组合约束、标定范围和上下文约束校验。
4. `SceneConfig` 额外校验引用存在、domain 一致、step id 唯一且依赖图无环。
5. `CommandPlan` 额外校验所有 bus/message/signal 均存在于选定平台定义。

JSON Schema 使用 Draft 2020-12。配置文件推荐 YAML，服务接口使用相同字段的 JSON 表示。

## 文件类型

- `intent-ir.schema.json`：自然语言解析后的稳定中间表示。
- `function-config.schema.json`：单领域功能配置公共外壳。
- `function-preset.schema.json`：领域模式/预设定义。
- `scene-config.schema.json`：跨域主场景配置。
- `command-plan.schema.json`：确定性 CAN 命令计划，禁止任意 raw payload。
- `trace-event.schema.json`：前端进度和审计事件，不包含私有思维链。
- `execution-report.schema.json`：执行结果汇总。
- `domain-manifest.schema.json`：领域插件注册信息。
- `capability-catalog.schema.json`：提供给 Router、LLM 和 UI 的领域能力目录。
- `signal-mapping.schema.json`：语义参数到平台 DBC/Compiler handler 的映射。
- `platform-manifest.schema.json`：车型 DBC、总线、领域和标定资源清单。


## 兼容性

`apiVersion` 表示公共对象结构版本，`metadata.version` 表示该配置实例或插件的内容版本。消费者遇到不支持的 `apiVersion` 必须拒绝执行，不能静默忽略未知必填语义。