开发文档
通用 OTA 服务的接入协议、状态码与升级流程。
与代码同源维护，同步后在此查阅最新版本。
OTA 在线升级
通用全协议 OTA 服务（TCP / MQTT / HTTP）。TCP 通道已拆成客户端接入手册与服务端手册两份。
客户端手册 设备端 / App 接入
TCP OTA 客户端接入手册
设备端视角：帧格式（14 字节头 / 6 种帧类型）、握手与心跳、8 个动作与全部字段、err 0~14 与链路级错误码全表、全量与差分升级流程，附可直接运行的 Python 参考客户端。
MQTT OTA 客户端手册
设备端视角：主题与 QoS（ota_device/… 与 ota_server/…）、event 事件码与 status 状态码、查询更新、固件下载与校验、结果上报。章节骨架已列出，正文待补充。
HTTP OTA 客户端手册
App / 上位机视角：接入信息与鉴权、四个 REST 接口（/ota/check、/ota/download、/ota/delta、/ota/changelog）、状态码与错误处理、Range 断点续传。章节骨架已列出，正文待补充。
服务端手册 服务端实现 / 运维
TCP OTA 服务端手册
服务端视角：帧收发契约、多设备并发的 sid 回显、8 个动作处理规则、错误码触发场景全表、分片与会话参数、发送队列与 again 流控、灰度 / 写锁 / 限速，含自检命令与故障对照表。
MQTT OTA 服务端手册
服务端视角：Broker 与主题命名、事件码 / 状态码定义、请求处理与响应规则、分片下发与 QoS 重传、会话超时、主动下发、灰度与写锁、排障。章节骨架已列出，正文待补充。
HTTP OTA 服务端手册
服务端视角：鉴权与限流、接口实现与字段判定、错误码触发场景、Range 与断点续传、缓存策略、日志与排障。章节骨架已列出，正文待补充。
维护须知
文档源头（改这里）
ota/docs/web/
同步命令
ota/scripts/sync_dev_docs.sh
同步校验（Agent 收尾必跑）
ota/scripts/sync_dev_docs.sh --verify
线上副本（勿手改）
web_server/dev_docs/ota/
维护说明
ota/docs/开发文档维护说明（Agent 必读）.md
改完文档必须执行同步脚本，再用 --verify 确认（退出码 0 = 副本与源头一致）——
否则本页读到的是旧副本。页首「最近同步」时间与文件数取自 ota/manifest.json，
可直接判断是否落后。Agent 执行清单见维护说明 §0。