EdgeMesh 网络协议规范

1. 定位与边界（先读这章）

1.1 EdgeMesh 负责什么 / 不负责什么

1.2 与 EdgeMemory / EdgeHippo 的分界

EdgeHippo   = 硬件：跑协议的物理设备
EdgeMesh  = 网络：设备之间怎么找到彼此、怎么搬碎片、怎么记账
EdgeMemory= 软件：碎片在板内怎么存、怎么查、怎么保持一致

EdgeMesh 不得直接访问 flash 或写库 —— 它只调用 EdgeMemory 的
  em_frag_import / em_frag_export / em_sync_* 接口。

2. 拓扑与节点类型

        ┌──────────────┐
        │   Hub        │  EdgeHippo Dev-B (form=usb-dongle, N16R8, 12,900 条)
        │  (relay)     │  代持转发 · 账本仲裁
        └───┬──────┬───┘
     BLE/ Wi-Fi    Wi-Fi/HTTP
        ┌──┘        └──┐
  ┌─────▼─────┐   ┌────▼──────┐
  │  Peer #1  │   │  Peer #2  │   EdgeHippo Dev-A (form=gamma-card, N8R8, 3,700 条)
  │  Dev-A    │   │ (second)  │   各装「专家记忆包」
  └───────────┘   └───────────┘
        └────── UART1 备用互联 ──────┘

现有 link_mgr 已实现 1 usb-dongle + 2 gamma-card 的 BLE 互联拓扑（原记作「1 gateway + 2 edge」，属板级角色表述），EdgeMesh 直接复用其链路管理，只替换上层语义。

3. 传输承载矩阵

4. 设备发现与标识

4.1 设备 ID

格式：EME-<MAC 后 3 字节大写 HEX>
例：  EME-21E980（Dev-B，MAC 14:C1:9F:21:E9:80）
     EME-71FAC8（Dev-A，MAC 44:BD:8D:71:FA:C8）

旧前缀 EMGW- 在 MVP 期间仅做兼容识别，不再新发。em_dev_is_placeholder_id() 已有占位 ID 检测逻辑，须同步更新前缀判断。

4.2 能力通告（advertise）

每个设备周期性广播自己的碎片目录摘要，不是全量内容：

{
  "msg": "mesh.advert",
  "body": {
    "dev": "EME-21E980",
    "form": "usb-dongle",        /* 板级形态标识（gamma-card / usb-dongle），非角色 */
    "cap_kb": 12900,          /* 容量上限 */
    "used_kb": 8412,          /* 已用条数 */
    "frags": [                /* 只列摘要，不列内容 */
      {"id":7,"name":"docs-core-v1","scene":3,"ver":3,"count":6000},
      {"id":9,"name":"expert-pack-v3","scene":2,"ver":3,"count":1800}
    ],
    "bearers": ["wifi","ble","usb"],
    "uptime_s": 12345
  }
}

4.3 发现流程

1. 设备上电 → 广播 mesh.advert（BLE 广播包 / HTTP mDNS / UDP 组播）
2. 中转方（Hub）收到 → 记录到邻居表（带 TTL，默认 120 s）
3. link.scan / hub.discover 命令返回邻居表
4. 未配对的设备 LED 白双闪；互联断开时黄慢闪（01 号分册第 8 章）

5. 消息 envelope

所有 EdgeMesh 消息（无论承载）共用同一 envelope。BLE 上用精简二进制变体，HTTP / 串口 / USB 用 JSON。

{
  "v":    1,                        /* 协议版本 */
  "src":  "EME-71FAC8",            /* 源设备 ID */
  "dst":  "EME-21E980" | "*",      /* 目的，* = 广播 */
  "msg":  "mesh.query",             /* 原语名 */
  "seq":  1234,                     /* 单调序号，用于去重与应答配对 */
  "ttl":  4,                        /* 跳数上限，防环路 */
  "ts":   1770000000000,            /* 毫秒时间戳 */
  "tok":  "…",                      /* 配对 token（配对后必填） */
  "body": { … }                     /* 原语专属 */
}

5.1 应答 envelope

{ "v":1, "src":"EME-21E980", "dst":"EME-71FAC8",
  "msg":"mesh.result", "seq":1234, "ack_seq":1234,
  "body":{ "code":0, "msg":"ok", "data":{ … } } }

/* 错误码 */
0   OK
1   ERR_BAD_REQUEST      参数错
2   ERR_UNAUTHORIZED     未配对 / token 无效
3   ERR_NOT_FOUND        碎片不存在
4   ERR_QUOTA_EXCEEDED   配额不足
5   ERR_BUSY             正在导入/导出
6   ERR_CLOCK_SKEW       时钟偏差过大
7   ERR_STORAGE_FULL     容量不足
8   ERR_CRC              数据校验失败

6. 协议原语（六种）

复用现有 /api/mesh/* 端点与 mesh.* 命令，消息名保留，字段从「算力竞标」重定义为「碎片接力」（ADR-011）。

6.1 一次完整接力的时序

Peer(Dev-A, γ 磁吸卡形态)           Hub(Dev-B, β USB Dongle 形态)
    |--- mesh.query {scene:2} ------->|      我要野外巡检的碎片
    |<-- mesh.bid {frag:9, quota:12} -|      我有 expert-pack-v3，12 配额
    |--- mesh.request {frag:9} ------>|      请给我
    |<-- mesh.result chunk 0/87 ------|
    |<-- mesh.result chunk 1/87 ------|      4 KB 分块 + CRC32
    |       … 断点续传 …              |
    |--- mesh.award {quota:12} ------>|      记账：我给你 12 配额
    |<-- mesh.result {code:0} --------|
    |                                 |
    |  em_frag_import → 事务提交 → LED 蓝快闪结束 → 绿常亮

7. 三种碎片接力模式

7.1 M3 离线投递的回执格式

/* 投递方生成 .emf 时同时生成 .emr（回执） */
{
  "v":1,
  "from":"EME-21E980",
  "to":"*",                       /* 未知目的，联网后补 */
  "frag_id":9, "name":"expert-pack-v3", "ver":3,
  "bytes":1188000, "quota":36,
  "delivered_ms":1770000000000,
  "crc32":"0x8A3F2C11"
}
/* 接收方联网后把 .emr 回传给 Hub，Hub 合并进账本 */

8. 账本与配额（合规红线）

8.1 配额的定义

8.2 记账规则

1. 每条账目：{seq, from, to, frag_id, bytes, quota, ts}，seq 设备内单调
2. 双向一致：请求方记「−quota」，提供方记「+quota」。对账误差必须为 0（G9）
3. 配额不足 → 返回 ERR_QUOTA_EXCEEDED，不得降级为「先给数据后补账」
4. 账本只保留最近 N 条（默认 4,096），超出滚动覆盖，但必须保证已对账区段不被覆盖
5. 账本参与 store.map 的同源输出（02 号分册 6.2 节）

8.3 UI / 文案禁用词（发布前逐屏检查）

禁止出现：钱包、币价、代币、代币化、提现、收益、挖矿、算力市场、交易、撮合、上币、持仓、K 线、DePIN、RWA。

可用表述：配额、协作计量、记账、点对点同步、知识接力。

9. 一致性模型与冲突消解

9.1 两级一致性

9.2 冲突消解规则

10. 安全

11. 现有固件改造清单

12. 测试用例索引

完整用例见 05 号分册 TC-M-*（12 条）。本节列出覆盖矩阵，便于查漏补缺。