TCP
TCP OTA 客户端接入手册
设备端视角：帧格式（14 字节头 / 6 种帧类型）、握手与心跳、8 个动作与全部字段、 应用层错误码 0~14 与链路级错误码 0x01~0x04 全表、全量与差分升级流程、 三个必须实现的细节、常见问题，附可直接运行的 Python 参考客户端。
客户端手册 · 设备端 / App
MQTT
MQTT OTA 客户端手册
设备端视角：主题与 QoS（ota_device/… /
ota_server/…）、event 事件码与 status 状态码、
查询更新、固件下载与校验、结果上报。当前为目录骨架，正文待补充。
HTTP
HTTP OTA 客户端手册
App / 上位机视角：接入信息与鉴权、四个 REST 接口
（/ota/check、/ota/download、
/ota/delta、/ota/changelog）、
状态码与错误处理、Range 断点续传。当前为目录骨架，正文待补充。
服务端手册 · 服务端 / 运维
SRV
TCP OTA 服务端手册
服务端视角：帧收发契约、多设备并发的 sid 回显、8 个动作的处理规则、
错误码触发场景全表、分片与会话参数、发送队列与 again 流控、
灰度 / 写锁 / 限速，以及自检命令与故障对照表。
MQTT
MQTT OTA 服务端手册
服务端视角：Broker 与主题命名、事件码 / 状态码定义、请求处理与响应规则、 分片下发与 QoS 重传、会话超时、主动下发、灰度与写锁、排障。当前为目录骨架，正文待补充。
HTTP
HTTP OTA 服务端手册
服务端视角：鉴权与限流、接口实现与字段判定、错误码触发场景、 Range 与断点续传、缓存策略、日志与排障。当前为目录骨架，正文待补充。
文件结构与维护说明
docs/web/
├── index.html 入口页（本页）：协议总览 + 页内加载子页
├── assets/
│ ├── doc.css 两页共用的排版样式（含深色主题、打印样式）
│ └── doc.js 共用脚本：目录自动生成 / 目录搜索 / 滚动高亮 / 代码复制 / 表格过滤
└── sub_web/ 协议子页（更深一层）
├── tcp_ota_client.html TCP OTA 客户端接入手册（完整）
├── tcp_ota_server.html TCP OTA 服务端手册（完整）
├── mqtt_ota_client.html MQTT OTA 客户端手册（目录骨架）
├── mqtt_ota_server.html MQTT OTA 服务端手册（目录骨架）
├── http_ota_client.html HTTP OTA 客户端手册（目录骨架）
└── http_ota_server.html HTTP OTA 服务端手册（目录骨架）
· 命名约定：一个协议两份文档 —— <协议>_client.html（客户端手册）
与 <协议>_server.html（服务端手册），两份互相链接。
· 新增协议：在 sub_web/ 下照抄任一骨架页，改标题与章节，再在
index.html 里复制一张卡片（data-key /
data-target / data-title）即可，
入口页的协议下拉与哈希路由会自动带上它（index.html#tcp-client 直达）。
· 子页章节：<h2> / <h3>
会自动生成左侧目录；标题形如 一、接入信息、
1、整体链路 时自动拆成「编号 + 名称」两列。
· 表格加 data-filter="提示文字" 即出现行过滤框（状态码表已启用）。
· 本地预览（避免个别浏览器对 file:// 内嵌页面的限制）：
python3 -m http.server -d /home/user/install/ota/docs/web 8099 # 然后浏览器打开 http://127.0.0.1:8099/
提示：子页自身带有左侧章节目录（支持搜索、滚动高亮，快捷键 /）。
若浏览器阻止了本地内嵌页面加载，请点「在新窗口打开 ↗」。