diff --git a/README.md b/README.md
new file mode 100644
index 0000000..d9ffb59
--- /dev/null
+++ b/README.md
@@ -0,0 +1,33 @@
+# WH Telemetry Protocol（WHTP）
+
+> A lightweight, self-describing telemetry protocol based on UTF-8 JSON
+
+WH Telemetry Protocol（简称 **WHTP**）是一套面向物联网场景的 **JSON 遥测上行协议**。它强调 **自描述能力** 与 **轻量化设计**，在带宽、功耗与开发效率之间取得平衡，帮助设备端与云端快速完成数据对接。
+
+## 特性亮点
+
+- **自描述（Self-descriptive）**：数据类型、单位、采样间隔等元信息随报文一并上送，脱离外部 Schema 亦可独立解析。
+- **单一载体（JSON）**：无需生成器或专用编解码库，主流语言天然支持。
+- **时间表达力强**：支持从秒到纳秒的多粒度 UNIX 时间戳，或 ISO-8601 字符串。
+- **批量数据友好**：内置等间隔 `array<T>` 与非等间隔 `irregular<T>` 两种批量格式，可显著降低消息数。
+- **枚举支持**：全局或内联枚举可读性强，兼具类型安全。
+- **错误／置信度模型**：统一的 `error_code` + `confidence` 机制，便于数据质量管理。
+- **多传输层**：已提供 [MQTT 补充说明](mqtt.md)，亦可轻松扩展至 HTTP、WebSocket、CoAP 等。
+
+## 快速上手
+
+1. 阅读主规范 [schema.md](schema.md)，了解字段定义与类型系统。
+2. 查看 [example.jsonc](example.jsonc) 获取完整示例。
+3. 若采用 MQTT 作为载体，参考 [mqtt.md](mqtt.md) 的主题、QoS、Retain 与连接安全实践。
+4. 参见 [schema.json](schema.json) 获取 [JSON Schema](https://json-schema.org/) 定义。
+
+## 仓库结构
+
+| 路径            | 说明                              |
+| --------------- | --------------------------------- |
+| `schema.md`     | WHTP 主规范（协议字段与类型定义） |
+| `mqtt.md`       | MQTT 传输层补充说明               |
+| `example.jsonc` | 完整示例消息，含字段注释          |
+| `README.md`     | 当前文件，项目概览                |
+
+
diff --git a/mqtt.md b/mqtt.md
new file mode 100644
index 0000000..6482fad
--- /dev/null
+++ b/mqtt.md
@@ -0,0 +1,71 @@
+# WH Telemetry Protocol over MQTT 补充说明
+
+本文件提供将 WH Telemetry Protocol（WHTP）封装并传输于 MQTT 的推荐做法与约定，用于指导设备端、边缘网关及云端服务的接入与实现。
+
+> 本文档为补充说明，仅描述 **传输层**（MQTT）相关约定。**应用层载荷** 仍遵循主规范 [WH Telemetry Protocol Specification](schema.md)。
+
+## 总览
+
+1. **主题命名**：采用层级语义化主题，便于基于通配符的订阅聚合。
+2. **QoS**：默认使用 QoS1（至少一次），对高可靠性场景可使用 QoS2；不建议使用 QoS0。
+3. **Retain**：遥测上行包默认不使用 Retain；状态类消息（如 LWT）可 Retain。
+4. **连接安全**：~~TLS 是推荐选项，并配合基于证书或 Token 的双向认证。~~ 目前为调试期间, 使用无加密的 MQTT 连接的 1883 端口, 请生产方做好随时更换为 TLS 的准备
+5. **会话管理**：生产端保持持久会话（Clean Start = 0），避免在网络抖动时丢失消息。
+
+## 连接与认证
+
+| 项目         | 建议                                                                                                            |
+| ------------ | --------------------------------------------------------------------------------------------------------------- |
+| 端口         | ~~`8883`（TLS）~~ / `1883`（非 TLS，仅调试）                                                                    |
+| 加密         | ~~启用 TLS 1.2+；设备应校验服务器证书~~ 调试阶段无加密, 使用无验证方式传输                                      |
+| 客户端标识符 | 使用设备 ID (`dev_id`)                                                                                          |
+| 认证方式     | ~~(1) 双向 TLS + 设备证书<br/> (2) Username/Password 传递 JWT/OAuth2 Token~~ 调试阶段无认证, 使用无验证方式传输 |
+| Keep-alive   | 60s–180s; 服务器以 1.5 倍 keep-alive 作为超时阈值                                                               |
+
+## 消息主题
+
+假设设备唯一标识 `dev_id = 148413b4-c352-49a9-9c48-9d15276a99e7`，则常用主题如下：
+
+| 方向 | 主题模板            | 示例                                           | 说明                                 |
+| ---- | ------------------- | ---------------------------------------------- | ------------------------------------ |
+| 上行 | `/whtp/up/{dev_id}` | `whtp/up/148413b4-c352-49a9-9c48-9d15276a99e7` | 发送遥测数据（Payload 为 WHTP JSON） |
+
+
+## QoS 与重传策略
+
+| 场景     | 建议 QoS | 说明                                                 |
+| -------- | -------: | ---------------------------------------------------- |
+| 遥测数据 |        1 | 至少一次，可接受少量重复；设备收到 PUBACK 即视为成功 |
+| 关键告警 |        2 | 云端必须且仅一次收到                                 |
+
+> [!NOTE]
+> **重复消息去重** 使用 `root.metadata.seq`（循环计数）及 MQTT 报文 `packetId` 实现。
+
+## Payload 格式
+
+MQTT Payload **必须**为 UTF-8 编码的文本，遵循 [WHTP 主规范](schema.md)。
+
+```jsonc
+// 示例：设备侧发布
+Topic   : /whtp/up/148413b4-c352-49a9-9c48-9d15276a99e7
+QoS     : 1
+Retained: false
+Payload : {
+  "version": 1,
+  "msg_type": "telemetry",
+  "dev_id": "148413b4-c352-49a9-9c48-9d15276a99e7",
+  "dev_type": "device_type_name",
+  "timestamp": 1715145600,
+  "fields": [
+    { "id": "temperature", "value": 23.5, "metadata": { "data_type": "number", "unit": "Cel" } }
+  ]
+}
+```
+
+## 最佳实践
+
+1. **批量上传**：对高频采样数据使用 `array<T>` 或 `irregular<T>`，显著降低 MQTT 消息数。
+2. **压缩**：在弱网场景可使用 MQTT v5 `content-type: application/json` + `payload-format-indicator:1` 并启用网关级 gzip。
+3. **流控**：设备端应监控 `MQTT_backpressure`，在云端未及时 ACK 时，暂存数据并退避重发，避免阻塞实时队列。
+4. **时间同步**：定期通过 NTP 或云端 SNTP 服务校准，确保时间戳精度。
+5. **错误处理**：当 `error_code ≠ 0` 时，建议 `confidence = 0` 并增加 `error_msg`，便于云端告警。
diff --git a/READMD.md b/schema.md
similarity index 98%
rename from READMD.md
rename to schema.md
index 55a8a9e..b47555f 100644
--- a/READMD.md
+++ b/schema.md
@@ -1,4 +1,4 @@
-# WH Telemetry Protocol
+# WH Telemetry Protocol Specification
 
 WH Telemetry Protocol（简称 WHTP）是一套以 JSON 为载体的遥测数据上行协议，强调自描述能力与轻量化设计，适用于物联网设备与云端之间的高效数据传输。
 
@@ -85,9 +85,10 @@ type Timestamp =
 > [!NOTE]
 > 根级 (root-level) 时间戳表示消息生成或入队时刻, 字段级 (field-level) 时间戳表示实际数据采样时刻, 应使用字段级时间戳进行所有时间序列分析
 
-### field 字段 (`fields`)
+### 消息描述字段组 (`fields`)
 
-必填。`Field` 对象数组，数组中每个元素代表一个测量项，其 `id` 在同一条消息内必须唯一。关于 `Field` 对象的定义详见后文 "field 字段" 章节。
+必填。`Field` 对象数组，数组中每个元素代表一个测量项，其 `id` 在同一条消息内必须唯一。
+关于 `Field` 对象的定义详见后文 ["消息描述字段"](#%E6%B6%88%E6%81%AF%E6%8F%8F%E8%BF%B0%E5%AD%97%E6%AE%B5) 章节。
 
 ### 消息元数据 (`metadata`)
 
@@ -175,7 +176,7 @@ type Location = {
 type UserData = Record<string, any>
 ```
 
-## 消息描述字段 (fields)
+## 消息描述字段
 
 ### 标识符 (`id`)