定义
Device Shadow（设备影子）是设备在云端的虚拟表示，存储 Desired State（期望状态）与 Reported State（上报状态）。设备离线时，平台可将下行指令写入影子，待设备上线后拉取执行，确保配置不丢失。
核心特点
- 离线缓存：配置下发可写入影子，设备上线后自动拉取
- 状态同步：期望状态与上报状态对比，支持配置最终一致
- 远程控制：与 Remote Control 配合实现离线指令缓存
工作流程
应用或平台写入 Desired 期望状态至影子；设备上线后订阅影子 Topic，拉取 Delta（期望与上报的差异），执行配置更新后上报 Reported 状态；平台合并 Reported 与 Desired，实现最终一致。设备离线期间，Downstream Command 下行指令可写入影子，设备上线后自动同步，无需轮询。
与物模型的关系
影子存储的内容遵循 Thing Model 物模型定义的属性结构。支持部分更新（仅更新指定属性）、版本号（防止并发冲突）。适用于配置下发、远程开关控制、参数批量更新等场景，是 Remote Control 远程控制的核心机制之一。
期望值和上报值何时算对齐
设备影子的技术含义，是在云端为每台设备保存两份按物模型组织的状态：希望它变成的期望值，以及它自己报告的实际值。两者的差才是待执行的内容。设备在线时，平台可以把差推下去；设备离线时，差留在影子里，等会话恢复再取。对齐不是指云端写过一次，而是指上报值已经覆盖了对应的期望，或设备明确拒绝并给出原因。没有上报之前，期望只是意图。版本号用来拒绝过期的写入，后到的旧请求不能覆盖先到的新请求。
适合放进影子的，是幂等的期望配置，例如目标开关、目标阈值。不适合的是每一次都必须按顺序执行、不能合并的瞬时动作，例如“点动一下”。使用影子的前提，是属性在物模型里有明确类型，设备知道如何读取差并在完成后上报。部分更新只能改指定属性，未出现的属性应保持原样，不能因为这次请求没带就把其他期望清掉。与连接状态配合时，离线期间可以积累期望，但界面要标明这些值尚未被设备确认。已退役的设备不应继续接受新的期望写入。
离线指令叠在一起后谁覆盖谁
常见错误是把多次修改同一属性都排成队列，设备上线后从旧到新逐条执行。影子的常规语义是同一属性只保留最新期望，中间值没有独立意义；若业务真要依次执行，就不应只用影子覆盖。另一种错误是设备上报了实际值，云端却不清除已完成的差，于是每次重连都把旧期望再写一遍，现场看到参数被反复改回。版本号不检查时，两个操作者同时修改，慢的那一次会赢。本地改过的参数如果被上报覆盖期望，还会把云端刚刚下发的目标冲掉，两边互相覆盖。
期望和上报的结构不一致，例如云端多了设备固件还不认识的字段，整包差会被设备拒绝，连同认识的字段一起失败。应当允许设备按已知字段执行，并上报自己不认识什么。时间戳用设备本地时钟且时钟是错的，版本比较会乱。影子成功写入也不等于执行成功，设备监控里要能看见“已期望、未上报”这一段，而不是设备一直离线、上线后却没有任何痕迹。清理影子时不能顺手删掉尚未确认的期望，除非有人明确放弃这些配置。
同一属性只留最新期望
影子里的同一个属性，常规语义是只保留最新的期望，而不是把每一次修改排成必须逐条执行的队列。离线期间被人改了三次阈值，设备上线后应看到最后一次，中间两次没有独立的执行意义。若业务确实要求按顺序点动，这种动作不该只靠覆盖式的影子来记。设备上报实际值之后，已经完成的差要清掉，否则每次重连都会把旧期望再写一遍，现场看到参数反复跳回。两个操作者同时修改时，版本较旧的请求必须被拒绝，不能因为后到达就覆盖新的目标。本地被人改过的值如果无条件反向覆盖云端期望，两边会互相改写，谁也稳定不下来。
设备还不认识的新字段，不应导致整包差异被拒绝。它应执行自己认识的部分，并说明哪些字段被跳过。写入影子成功只表示云端记下了意图，在设备上报之前，界面必须显示尚未确认，不能显示成已经生效。清理档案或重置影子时，尚未确认的期望要被明确放弃，不能在无人知晓的情况下删掉，也不能在设备已经退役之后继续保留并在偶然上线时执行。部分更新未提到的属性应保持原样，一次只改开关的请求不能把其他阈值清成空。