集成数据协议 v1 alpha 1

本页帮助中文用户理解协议。带标签版本中的英文规范、JSON Schema、测试夹具和 TCK 才是规范性依据。

权威来源：AetherContracts。

这套协议用于描述边缘本地委托设备提供方给出的完整设备拓扑和类型化观测。它不绑定行业， 也不绑定某一个厂商。Home Assistant 是第一个公开映射，但公共消息中没有 Home Assistant 的服务调用、实例地址、访问令牌或任意属性对象。

协议本身不负责传输，也不包含物理控制命令。CloudLink 的独立 Integration 扩展可以原样 承载这些对象，并继承会话、摘要、重放和持久确认规则。该扩展不会把提供方凭据迁移到 AetherCloud，也不会让云端成为实时状态权威。AetherEdge 负责把提供方证据接纳到本地 模型、执行安全策略，并决定任何独立受治理能力是否可以接触物理世界。

完整拓扑快照

拓扑快照使用 aether.integration.topology-snapshot.v1alpha1。每个快照把一个集成实例 及其类型绑定到确定的拓扑代次、观测时间，以及完整的区域、设备和实体列表。

它是一次完整替换，不是局部补丁：

• snapshot_generation 是规范的无符号 64 位整数文本；拓扑变化时必须递增。
• 消费方必须先验证整个候选快照，再原子替换上一代。
• 实体只在后续成功接纳的完整快照中缺失时，才可视为被删除。
• entity_id 是稳定的注册表身份；source_address 是当前接入方地址，可以随用户重命名而变化。
• 一个实体可以公开多个类型化点位。例如温控实体可以分别公开当前温度、目标温度和工作模式。

区域、设备、实体、来源地址，以及同一实体内的点位键都必须唯一。设备和实体引用的区域或 设备必须存在于同一份快照中。身份冲突会在悬空引用检查之前被拒绝，避免同一个错误被不同 实现解释成不同结果。

integration_kind 和 entity_kind 是受限标识符，但不是封闭的厂商枚举。核心代码不应 通过固定的厂商列表分支，否则新增提供方就会迫使公共协议升级。

类型化观测

观测批次使用 aether.integration.observation-batch.v1alpha1。每个批次必须绑定准确的 集成实例和拓扑代次；每条观测必须指向该代次内已经声明的实体和点位。

支持的值是封闭联合类型：

类型	表示方式
boolean	布尔值
int64	有符号 64 位整数的规范十进制文本
uint64	无符号 64 位整数的规范十进制文本
float64	有限浮点数
decimal	无指数、无多余前导零和尾随零的规范十进制文本
string	有长度上限的 Unicode 文本
bytes	不带填充的 Base64url 文本

质量为 good 或 uncertain 时必须带值；质量为 bad 或 unavailable 时禁止带值， 但可以附带受限诊断。使用方必须依次确认拓扑代次、实体、点位、质量和值的关系，最后检查 值类型。它不能把字符串 "on" 猜成布尔值，不能截断整数，也不能自行推断单位。

Home Assistant 映射

Home Assistant 注册表条目标识映射为稳定的 entity_id，当前实体地址映射为可变的 source_address。因此用户重命名实体不会在 Aether 中创建一个新设备，也不会让旧的 云端控制意图被重定向到另一个实体。

状态和经过选择、受大小限制的属性会变成预先声明的独立点位。任意属性不会整包复制到 公共协议中。质量映射如下：

• 可用且类型正确的状态映射为 good；
• 暂时陈旧但仍可使用的保留值映射为 uncertain；
• 接入方错误且没有可信值时映射为 bad；
• unknown 或 unavailable 且没有值时映射为 unavailable。

权威与证据边界

提供方地址、访问令牌、刷新令牌、Cookie、凭据引用、原始诊断载荷和任意提供方属性都不 属于该契约。秘密只能留在边缘本地密钥存储中，不得进入公开夹具、审计载荷、提示词、云端 投影或 CloudLink 消息。

一条被接纳的观测只证明提供方报告了该状态。Home Assistant 接受一次服务请求，也只证明 请求被它接纳，不能独立证明无线报文到达设备或执行器已经动作。边缘决定、提供方接受、 后续状态观测和物理确认必须作为不同证据保存。

可读显示字段和诊断字段必须至少包含一个非空白字符，并且不得包含 C0 控制字符或 DEL。 各字段仍受结构定义中的长度限制；违反时返回 TEXT_INVALID。这些字段只是标签和证据， 不能承载原始提供方载荷、秘密或终端控制序列。

传输和一致性

只读集成扩展名为 aether.cloudlink.integration.v1alpha1。它必须由运行时清单明确声明， 并使用 CloudLink 的会话、凭据代次、流位置、摘要、精确重放和连续持久确认规则。

规范结构位于 schemas/integration/v1alpha1/，一致性测试固定了身份、引用、代次、值类型、 质量、整数范围、十进制和 Base64url 行为。

0.1.0-alpha.4 是尚未发布的开发目标，仍处于实验阶段；最新发布版本仍是 v0.1.0-alpha.3，且不包含该扩展。alpha.4 源码声明公共数据契约、实验性 CloudLink Integration 封装及其仓库 TCK。该模块保持只读，不声明完整 AetherEdge 适配器、云端投影、 两个扩展的语言绑定支持或生产消息代理与重启证据。设备控制由独立、默认关闭的 Integration Control 规范定义。