edge

docs/EDGE_UPLINK_PROTOCOL_v1.md

@@ -4,6 +4,7 @@
 
 - **数据面**：`DATA_RAWBUS`（载荷语义对齐 [`RawBusMessage`](file:///home/dt/myCode/bus/soft_bus/softbus_daemon/src/core/models/RawBusMessage.h)）
 - **控制面**：会话、`CTRL_TREE_*` 与 **反向同步** `CTRL_TREE_PROPOSE` / `CTRL_TREE_RESULT`
+- **调试面**：`DEBUG_TUNNEL`（双向 UTF-8 JSON，见 §10；须已 HELLO）
 
 边缘仓库应维护与本文档 **字节级一致** 的副本（如 `docs/UPLINK_PROTOCOL_v1.md`）。
 
@@ -36,6 +37,7 @@
 | 6 | TREE_PROPOSE | 边缘→核心 | UTF-8 JSON，见 §6 |
 | 7 | TREE_RESULT | 核心→边缘 | UTF-8 JSON，见 §7 |
 | 8 | REPORT | 边缘→核心 | UTF-8 JSON（预留） |
+| 9 | DEBUG_TUNNEL | **双向** | UTF-8 JSON，见 §10；**仅**在会话已 HELLO 后允许 |
 
 ## 4. HELLO（边缘→核心）
 
@@ -144,3 +146,34 @@ UTF-8 JSON：
 ## 9. 与 orchestrator / D-Bus
 
 核心侧设备树持久化与 `reconcile` 行为与现有 `patch_device_tree_node` 一致；本协议为 **额外入口**，不得绕过校验逻辑。
+
+## 10. DEBUG_TUNNEL（`frame_kind = 9`，双向）
+
+用于主机与边缘之间的 **调试指令与监控** 类 JSON，不替代 `DATA_RAWBUS` / `TREE_*` 控制面。
+
+### 10.1 会话要求
+
+- **两端**均须在 **HELLO 成功之后** 才能发送本帧；核心对未 HELLO 连接上的 `DEBUG_TUNNEL` 会断开（与 `TREE_FULL` 等下行一致）。
+- 载荷为 **UTF-8 JSON 对象**（建议总大小远小于 `maxFrameBytes`）。
+
+### 10.2 推荐信封（可选）
+
+为便于对账与过滤，建议载荷使用统一形状（实现不强制解析，可原样记录日志）：
+
+- `v`（integer）：信封版本，当前 **1**。
+- `from`（string）：`"host"` 或 `"edge"`。
+- `tsMs`（integer）：发送端单调时钟毫秒（如 `QDateTime::currentMSecsSinceEpoch()`）。
+- `body`（object）：实际调试负载（指令、采样快照、订阅键等由产品约定）。
+
+### 10.3 主机 → 边缘
+
+- 核心通过 `executeCommand` 的 action **`edge_debug_send`** 向指定 `edgeId` 的已 HELLO 会话 **编码一帧** `DEBUG_TUNNEL` 并写入 TCP。
+- `edge_debug_send` 的 `params`：**必填** `edgeId`；调试 JSON 可放在 **`debug` 对象**中，或省略 `debug` 时除 `edgeId` 外的其余 `params` 字段合并为 `body`；核心会再包一层 `v`/`from:"host"`/`tsMs`/`body` 后下行（见 `CommandDispatcher`）。
+
+### 10.4 边缘 → 主机
+
+- 边缘在已连接且 HELLO 后，将 JSON 对象编码为 `DEBUG_TUNNEL` 上行；核心在 `EdgeTcpIngressService` 中解析并 **打日志**（可扩展为内部总线/订阅）。
+
+### 10.5 与边缘 Ops HTTP 的关系
+
+- 边缘进程内 **`OpsUiHttp`** 提供本机 **`GET /debug_host`**（最近从主机收到的调试 JSON 环形缓冲）与 **`POST /debug_edge`**（将 body JSON 经 `DEBUG_TUNNEL` 发往核心），便于在现场用 `curl` 与核心侧 `edge_debug_send` 做 **闭环联调**。