跨产品契约¶
产品彼此自治，因此唯一能绑定套件的只有显式契约。它们保持小而精、带版本、厂商 中立；对契约的改动是套件级事件，而非局部重构。
契约清单¶
| 契约 | 双方 | 约定了什么 |
|---|---|---|
| 网关线协议 v1 | Link ↔ Edge | 南向网关链路（v1/gateway/*）的主题、帧与目录：遥测、属性、设备影子、命令、发现、OTA。已实现；在候选发布前冻结。 |
| SSO / OIDC 联邦 | Sphere ↔ Identity ↔ 产品 | 浏览器会话如何变成产品会话：要么票据移交，要么直接 OIDC 客户端。见 SSO 与 OIDC。 |
| 产物交接 | Forge → Horizon | 生产出的模型 / 应用包如何成为可 rollout 的产物。 |
| 边缘分发通道 | Horizon → Edge | Edge 本身、应用与模型如何被交付与更新。边缘 OTA 通道由 Horizon 拥有，而非 Edge。 |
契约状态
契约在候选发布前定稿；任何未达到契约就绪状态的内容会移出该次发布，而不是半成品 上线。各项具体状态在套件开发计划中跟踪。
契约规则¶
以下规则适用于上述每个契约，也适用于各产品的公开 API：
- OpenAPI 即规范。 API 以 OpenAPI 3.1 描述，规范与代码在同一次改动中同步更新。 规范必须能解析（作为契约的一部分被校验）；Sphere 与 Link 都内置 离线 Swagger UI，使气隙环境下的运维无需 CDN 即可查阅契约。
- 空数组是
[]，绝不为null。 客户端可以依赖这个形状。 - 不臆造语义。 平台从不猜测含义——例如单位只来自用户定义的描述符。
- 构造上中立。 契约保持协议、技术栈与厂商中立。通用接口不硬依赖特定边缘栈或 芯片厂商；厂商特有细节留在 Forge 内部。
- 迁移显式且可逆。 模式变更以编号的、成对 up/down 的迁移交付——绝不在启动时 自动变更。
- i18n 同进同出。 无硬编码的用户可见字符串；新键在同一次改动中落到两种语言。
仓库¶
每个产品都是 NereidAI 组织下的独立仓库；一次契约变更会同时触及契约文档与所有受 影响的实现，作为一次协调改动。