7.1 集群库架构：全局命令、角色模型与属性上报

7.1 集群库架构：词库的语法骨架

本节摘要：集群库的三个骨架设计——全局命令与簇特定命令的分工（读写属性走通用通道）、客户端与服务端角色模型（配对通信的方向基础）、属性上报机制（传感器省电汇报的标准方式）。本节是词典（下一节）与序列化（第三节）的语法前置。

一、两类命令：通用通道与专用动作

集群命令帧带一个"命令类别"标志，把命令世界劈成两半。全局命令对所有簇通用：读属性（按编号取值）、读属性应答、写属性（按编号赋值）、写属性应答、属性上报（主动上报某属性值）、上报配置（设定哪些属性何时上报）、发现属性（列出这个簇支持哪些属性编号）。簇特定命令则各簇自定义：开关簇的开与关、调光簇的"跳到某亮度并过渡"、警报簇的"开始鸣叫"。设计意图第四章提过：把绝大多数互操作压进声明式的属性读写，通用工具无需理解每个簇就能完成监视与基础控制；只有真正"动作性"的语义才做成专用命令。

一个实用的推论：拿到一台陌生设备，先发发现属性与读属性，几乎总能拼出它的状态全貌——这是现场排障与集成开发的起手式，不依赖任何厂商文档。

二、角色模型：谁问谁答

每个簇实例分饰两角。服务端是"数据的家"——属性存储在服务端（传感器的温度值、灯的开闭状态）。客户端是"发问方"——读写命令由客户端发出、服务端应答。注意角色与设备形态不绑定而与端点实现相关：传感器端点通常实现测量簇的服务端（它有数据），网关实现客户端；而灯的开关簇服务端在灯上，开关面板作为客户端发命令。这与第四章"输入簇输出簇"的方向约定严格对应：服务端对应输入（能听懂、存状态），客户端对应输出（主动说）。

绑定撮合的正是跨角色配对：开关端点的开关簇客户端输出，绑定到灯端点的开关簇服务端输入，方向自然成立。角色模型的存在让"配对"有了形式化判据——两侧角色互补，通信才能成立；工具里报"绑定方向错误"，指的就是两端都是客户端或都是服务端。

一次典型的属性读取会话（概念时序）：

网关(客户端)                    传感器(服务端)
   │── 读属性(簇=温度测量, 属性=温度值) ──▶│
   │◀── 读属性应答(状态=成功, 值=22.5℃) ──│
   
一次属性上报的周期流（网关只听不问）：

传感器 ──属性上报(温度=22.6℃)──▶ 网关     （按上报配置的周期自动发）
传感器 ──属性上报(温度=22.9℃)──▶ 网关     （或按阈值变化触发）
​

三、属性上报：传感器经济的支柱

轮询式监控（网关定时读属性）在 Zigbee 世界是反模式——休眠终端没法随时应答，频繁轮询还会把它们反复叫醒。属性上报机制把节奏反过来：网关下发上报配置，声明"这个属性每逢变化超过某阈值就报"或"每过某最长时间报一次"，之后传感器按自己的节律在醒着的窗口里主动上报，网关只管收。三重收益：省电（醒着顺手发报，不必为应答多醒）、省带宽（只在变化时说话）、省网关算力（被动接收）。

上报配置是集成开发里最值得花时间的参数：阈值太小变成刷屏广播，太大丢失过程细节；最长时间间隔是"还活着"的心跳，兼作离线判据。现场"数据不更新"类问题，十有八九是上报配置丢失或被重配——排查从读回上报配置开始。

图：集群库骨架三件套的关系

四、从语法看演化

全局命令的扩张史就是词库的成熟史。早期规范里读写属性就有，属性上报配置与发现属性是后来补强的——前者解决了轮询与休眠的冲突（传感器经济的支柱），后者让工具可以在零文档前提下探索陌生设备（生态工具链的地基）。统一版在此基础上继续加码（如批量读写属性减少往返），方向始终如一：把更多互操作塞进通用通道，把专用命令压到最少。

💡 关键直觉：判断一套设备词库设计得好不好，看它"属性覆盖率"——能用读写属性完成的比例越高，与第三方生态的兼容性就越好。满屏簇特定命令、属性寥寥的设计，是分叉年代私有思维的残留。

本节要点回顾

• 两类命令：全局命令撑起声明式互操作，簇特定命令只留真动作；陌生设备先发现属性再读属性；
• 两种角色：服务端存属性、客户端发问，角色与输入输出簇方向对应，绑定要角色互补；
• 上报机制：阈值加最长间隔两档配置，省电省带宽兼作心跳；数据断更先查上报配置；
• 演化方向：通用通道持续扩张、专用命令持续收缩，属性覆盖率即兼容性风向标；
• 本节坐标：语法在手，下一节翻词典——各领域核心簇清单与设备类型模板。

延伸：声明式的边界

属性思维强大但有边界。纯状态语义（亮度、温度、开关状态）是属性的舒适区；带过程语义的操作（"渐变到某亮度经某路径"这类多参数动作）、以及时序敏感的联动，仍需要簇特定命令或上层编排。成熟的设计判断是：能用属性表达的绝不造命令，属性表达不了的果断造命令，不要硬把过程塞进属性的形状里——两种误用都会让语义变味，互操作性反受其害。

常见问题

上报配置可以同时对一个属性设阈值和最长时间吗？

可以且推荐：阈值触发负责"变化即报"，最长时间负责"没变化也定期报一次"兼作存活心跳。两者是或的关系，任一满足即发。只配阈值不配最长时间的网络，静置设备失联与否无法判断——这是"离线检测失效"类配置问题的常见根因。

速查：全局命令清单

• 读属性 · 读应答：监视的基础；
• 写属性 · 写应答：控制的基础；
• 属性上报 · 上报配置：传感器经济的基础；
• 发现属性：零文档探索的基础。

配套起手式：发现属性 → 读属性 → 按需配置上报 → 必要时写属性或发簇命令。任何陌生设备的集成都从这四步开始。

补 ZCL 命令的三种消息模式，它是理解 ZCL 行为的钥匙。模式一，单播命令加响应：开关对某盏灯发 on/off 并要求 APS 确认——最常规的模式，可靠优先。模式二，组播：一个命令发给组内所有设备（开"客厅"组的三盏灯）——组播在网络层泛洪到组员，高效但要节制（组播是网状网络里的昂贵操作）。模式三，广播：全网所有设备收——只用于网络级管理命令，应用层慎用（广播的风暴成本见前文）。ZCL 还有"默认响应"机制（收到命令回一个 success 或 failure 的简短回复）——许多廉价设备省略默认响应，网关无从判断命令是否生效，只能盲等设备的状态上报。产品设计的建议：即便为了省电，控制类命令的默认响应也应该实现——它是网关判断"这条命令死了"的唯一依据，没有它，重试与告警机制都是瞎的。ZCL 的这些行为细节，决定了生态里设备的"素质分"——协议允许偷懒，生态会记住偷懒。