# VulpeCat 灵猫司海 · 船端接口文档 > 版本:v1(2026-11) > 适用对象:船端 ARM Linux 开发板(Rock 4D / RK3576 等)上的通信程序 > 服务端:`server/`(FastAPI),本文档描述的每一个端点都在服务端有实现 > 参考实现:`tools/fake_device.py`(纯标准库,可直接跑通下面所有流程) --- ## 1. 这套东西是怎么连的 ``` 船(4G) ──HTTP(S)──► FastAPI 服务端 ──WebSocket──► 浏览器控制台 船(2.4G)──► 船载基站 ──HTTP(S)──► 同上 ``` - 船端**只做两件事**:定期上报自己的状态、接命令并回执。 - 服务端负责保存船队状态、把命令排队下发、把它推给所有打开的控制台页面。 - 浏览器怎么连不用管,船端只对接本文档里的 `/api/v1/device/*`。 **两条链路的区别只有一个字段**:`data.link.has_video`。 `4G` 链路带图传(`true`),`2.4G` 基站链路不带图传(`false`)。控制台据此显示"该链路无图传",不会报错。 --- ## 2. 接入准备 ### 2.1 设备身份 每个设备用两个头部表明身份: | 头 | 说明 | | --- | --- | | `X-Device-Id` | 设备唯一 id,正则 `^[a-z0-9][a-z0-9_-]{1,31}$`,例如 `usv-01`、`lingmao-1` | | `X-Device-Key` | 设备密钥,见服务端 `config.json` 的 `device.key` | ```jsonc // config.json(服务端) { "device": { "key": "vulpecat-dev-key", // ← 所有设备共用的密钥,部署前改掉 "allow_unregistered": true, // true:任何 id 都能接;false:只允许 devices 里列出的 "devices": [ { "id": "usv-01", "name": "灵猫一号" } // 可选,作用是给设备起个中文名 ] } } ``` > `allow_unregistered: false` 时,未列在 `devices` 里的 id 会收到 `device_unknown`。 > 名字没配就显示 id。 ### 2.2 服务地址 本机调试:`http://127.0.0.1:8099` 船在 4G 上:填服务器的公网地址(或内网穿透地址)。**必须是 http(s),不要用 `file://`。** --- ## 3. 通用约定(先看这节,能省一半联调时间) | 项 | 约定 | | --- | --- | | 编码 | UTF-8,`Content-Type: application/json`,中文不转义 | | 坐标系 | **WGS84**,十进制度,`lat` 北正、`lon` 东正。天地图底图是 CGCS2000,与 WGS84 差异 < 1m,**不做纠偏** | | 精度 | 上报保留 6 位小数(≈0.11 m),多余位服务端截断 | | 艏向/方位 | `heading` / `cog` / `obstacles[].brg`:0–360°,**0 = 真北,顺时针**。往回走是 270 不是 -90 | | 姿态 | `roll` 右舷下沉为正,`pitch` 船首抬起为正,单位度 | | 速度 | `sog` 对地 m/s(**不是节**)。1 m/s ≈ 1.94 kn | | 距离 | 米 | | 时间 | `ts` = **整数毫秒 UTC**(`int(time.time()*1000)`)。服务端另存 `recv_ts`,界面显示一律用 `recv_ts`,所以**船端时钟不准不影响显示** | | 版本 | 每帧带 `"v": 1`。字段只增不改语义 | | 坐标系不要混 | 别把 GCJ02(高德/腾讯地图导出的坐标)直接发上来,会整体偏移几百米 | --- ## 4. 握手:`POST /api/v1/device/hello` 开机或重连后建议先调一次,确认密钥对、拿到服务端的限制参数。 ```bash curl -X POST http://127.0.0.1:8099/api/v1/device/hello \ -H "X-Device-Id: usv-01" \ -H "X-Device-Key: vulpecat-dev-key" ``` ```json { "ok": true, "v": 1, "dev": "usv-01", "server_ts": 1794897971435, "limits": { "telemetry_hz": 10, "queue_depth": 8, "cmd_ttl_ms": 15000 } } ``` 失败时返回 §9 的错误码,`ok` 为 `false`。 --- ## 5. 上行一:`POST /api/v1/device/telemetry`(推荐) **这个端点就是主循环。** 建议 2–5 Hz,响应里会顺带把待执行命令带回来,省一次往返。 ### 5.1 请求 ```bash curl -X POST http://127.0.0.1:8099/api/v1/device/telemetry \ -H "Content-Type: application/json" \ -H "X-Device-Id: usv-01" \ -H "X-Device-Key: vulpecat-dev-key" \ -d '{ "v": 1, "type": "telemetry", "dev": "usv-01", "seq": 48213, "ts": 1794897971435, "data": { "lat": 31.20769, "lon": 120.15612, "heading": 92.4, "cog": 92.0, "sog": 2.20, "stw": 2.31, "roll": -2.2, "pitch": 1.5, "yaw_rate": 4.1, "batt": 82.0, "volt": 24.8, "curr": 6.2, "gps": { "fix": 3, "sats": 13, "hdop": 0.8, "age_ms": 200 }, "link": { "type": "4g", "has_video": true, "rssi": -69, "rsrp": -88, "rtt_ms": 61, "loss_pct": 0.4, "up_kbps": 320, "down_kbps": 1800 }, "obstacles": [ { "brg": 108.0, "width": 26, "dist": 12.4, "level": 2, "src": "sonar" } ], "task": { "state": "route", "idx": 2, "total": 5, "eta_s": 214, "route_id": "r-77" }, "home": { "lat": 31.20700, "lon": 120.15500 }, "mode": "auto", "armed": true, "video": { "state": "live", "proto": "webrtc", "fps": 24, "kbps": 1400 }, "faults": [] } }' ``` ### 5.2 响应 ```json { "ok": true, "ts": 1794897971466, "commands": [ { "v": 1, "type": "cmd", "id": "c_9f2a1b7c01", "ship": "usv-01", "kind": "goto", "args": { "lat": 31.215, "lon": 120.165 }, "ts": 1794897970551, "ttl_ms": 15000, "seq": 17 } ] } ``` `commands` 是待执行命令数组,可能为空。**收到后必须按 §7 回 ACK**,否则控制台上会一直显示"等待船端确认",最后超时。 ### 5.3 稀疏补丁(省流量的关键) `data` 里的字段是**可选的、增量覆盖**的: - 没带的字段 → 服务端沿用上一次的值(比如电池 1 Hz 发一次,姿态 5 Hz 发) - `gps` / `link` / `task` / `video` / `home` → **整体替换**(要发就发完整的对象) - `obstacles` → **整体替换**,发 `[]` 表示"当前无障碍" ### 5.4 `seq` 的作用 每帧递增整数。服务端**丢弃 `seq <= 上次` 的帧**,用来挡重复包和乱序包。 > ⚠️ **设备重启后 seq 会从 0 重来,必须先调一次 `POST /device/hello`**(服务端会把这个基线清零), > 否则新帧永远小于旧值,会被一路丢弃——现象是"船一直显示离线,但抓包看请求都通了"。 > 这是 C/Python 都容易踩的坑:进程重启、看门狗复位、断电重启都算。 换用长轮询通道时尤其重要。 ### 5.5 字段表 | 字段 | 类型 | 单位/范围 | 必填 | 说明 | | --- | --- | --- | --- | --- | | `lat` `lon` | float | deg | 是 | GPS 定位 | | `heading` | float | 0–360 | 是 | 真北艏向(磁偏校正后)。只有磁力计时可发 `heading_mag` 并说明未校正 | | `cog` | float | 0–360 | 否 | 对地航向,无则用 `heading` | | `sog` | float | m/s | 是 | 对地速度 | | `stw` | float | m/s | 否 | 对水速度,有流速计才发 | | `roll` `pitch` | float | deg | 是 | MPU6050 / IMU 解算后的姿态角 | | `yaw_rate` | float | deg/s | 否 | 右转为正,姿态球横滚参考 | | `batt` | float | 0–100 | 是 | 剩余电量百分比 | | `volt` `curr` | float | V / A | 否 | 电池电压 / 电流 | | `gps` | object | — | 是 | `{fix, sats, hdop, age_ms}`;`fix`: 0=无 2=2D 3=3D 4=RTK | | `link` | object | — | 是 | 见下表 | | `obstacles` | array | — | 否 | 见下表 | | `task` | object | — | 是 | `{state, idx, total, eta_s, route_id}` | | `home` | object | — | 否 | `{lat, lon}` 返航点 | | `mode` | string | `manual`/`auto`/`hold`/`estop` | 是 | 控制模式 | | `armed` | bool | — | 是 | 推进器是否使能 | | `video` | object | — | 否 | `{state, proto, fps, kbps}` | | `faults` | array\ | — | 否 | 故障码,如 `["gps_lost","batt_low"]`(会在控制台提示) | **`link` 对象** | 字段 | 类型 | 说明 | | --- | --- | --- | | `type` | string | `4g` / `2.4g` / `wifi` / `eth` | | `has_video` | bool | **该链路是否具备图传**。`2.4g` 基站链路恒为 `false` | | `rssi` `rsrp` | int | dBm。4G 用两个;2.4G 只填 `rssi` | | `rtt_ms` | int | 设备 ping 服务端的往返延迟,30 s 测一次即可 | | `loss_pct` | float | 丢包率 % | | `up_kbps` `down_kbps` | int | 近 10 s 均值,控制台首页的流量条用它 | **`obstacles[]` 元素** | 字段 | 类型 | 说明 | | --- | --- | --- | | `brg` | float | **绝对方位角**(0=北,顺时针),不是相对船艏。船转向时障碍在世界里不动 | | `width` | float | 扇区张角(度),5–120 | | `dist` | float | 最近距离 m | | `level` | int | 0 提示 / 1 注意(<30m) / 2 警告(<15m) / 3 危险(<5m,控制台会告警) | | `src` | string | `sonar` / `lidar` / `vision` / `fused` | **`task.state` 取值**:`idle` 待命 / `goto` 单点航行 / `route` 航线 / `rth` 返航 / `hold` 保持 / `estop` 急停 / `fault` 故障 **`video` 对象**:`state` = `off` / `connecting` / `live` / `error`;`proto` = `webrtc` / `mjpeg` / `flv`。 目前控制台只显示图传状态与码率,播放器接口已预留(`Video.attach(kind, src)`)。 --- ## 6. 上行二:`GET /api/v1/device/commands`(长轮询) 嫌遥测带命令耦合太紧,或者想单独一个线程等命令,就用这个: ```bash curl "http://127.0.0.1:8099/api/v1/device/commands?wait=20" \ -H "X-Device-Id: usv-01" -H "X-Device-Key: vulpecat-dev-key" ``` - `wait` 秒内没命令就阻塞等待(最大 30,建议 20),超时返回空数组。 - 有命令立刻返回,格式同上:`{"ok":true,"ts":...,"commands":[...]}`。 - 命令一旦被取走就从队列删除,**两条通道不会重复投递**(但 ACK 仍要按 id 幂等处理)。 --- ## 7. 命令与 ACK ### 7.1 命令帧 ```json { "v": 1, "type": "cmd", "id": "c_9f2a1b7c01", "ship": "usv-01", "kind": "goto", "args": { "lat": 31.215, "lon": 120.165 }, "ts": 1794897970551, "ttl_ms": 15000, "seq": 17 } ``` | 字段 | 说明 | | --- | --- | | `id` | 命令 id,幂等键 | | `kind` | 命令类型,见下表 | | `args` | 参数对象 | | `ts` | 服务端生成时间(ms UTC) | | `ttl_ms` | 有效期。**`now - ts > ttl_ms` 必须拒绝执行**,见 7.3 | ### 7.2 命令表 | `kind` | `args` | 语义 | 说明 | | --- | --- | --- | --- | | `goto` | `{lat, lon, speed?}` | 单点航行 | 覆盖当前任务 | | `route` | `{points:[[lat,lon],...], loop?, speed?}` | 折线航线 | 2–50 个点 | | `rth` | `{}` | 返航到 `home` | home 未设则用首次定位点 | | `hold` | `{}` | 原地保持 | 闭环定点 | | `estop` | `{}` | 急停 | 立即断推进器输出,**跳过队列、不重试** | | `set_home` | `{lat?, lon?}` | 设返航点 | 缺省用当前船位 | | `arm` / `disarm` | `{}` | 解锁 / 上锁 | 上锁 = 断输出 + 清任务 | | `mode` | `{value: "manual"\|"auto"}` | 切手自动 | | | `video_start` / `video_stop` | `{proto?}` | 图传开关 | 无图传链路必须回 `unsupported` | | `clear_faults` | `{}` | 清故障码 | | ### 7.3 ACK:`POST /api/v1/device/commands/{id}/ack` **收到命令 3 秒内必须回**,否则控制台显示"船端未响应"。 ```bash curl -X POST http://127.0.0.1:8099/api/v1/device/commands/c_9f2a1b7c01/ack \ -H "Content-Type: application/json" \ -H "X-Device-Id: usv-01" -H "X-Device-Key: vulpecat-dev-key" \ -d '{"ok": true, "state": "accepted", "code": "ok", "ts": 1794897970702}' ``` ```json { "ok": true, "cmd_id": "c_9f2a1b7c01", "ts": 1794897970711 } ``` | `state` | 含义 | | --- | --- | | `accepted` | 收到、校验通过、开始执行 | | `rejected` | 拒绝(`ok:false` + `code`) | | `executing` | 执行中(可选,长任务用) | | `done` | 完成(可选) | | `failed` | 执行失败(`ok:false` + `code`) | **三条硬规则:** 1. **过期不执行**:`now_ms - cmd.ts > cmd.ttl_ms` → 回 `{"ok":false,"state":"rejected","code":"expired"}`,不执行。 这条是防"断网 5 分钟后突然收到一条去这里",把船开跑。 2. **幂等**:保留最近 32 个 `id` 的结果,重复 id 直接重发上次 ACK,不重复执行。 3. **先 ACK 再执行**:长任务先回 `accepted`,执行完可再回 `done`。别等做完才回,超时了控制台会报错。 ### 7.4 队列与重试 - 每条船队列深度 **8**,满了服务端返回 `queue_full`(前端会提示)。 - `estop` 插队,不受队列限制。 - 服务端投递后等 ACK,默认超时 **15 s**(即 `ttl_ms`)。超时前端显示"船端未响应"。 --- ## 8. 前端实时通道(船端不用实现,了解即可) `WS /api/ws/ui` 是浏览器用的,消息类型: | 类型 | 方向 | 用途 | | --- | --- | --- | | `hello` | 服务端→前端 | 连接/重连时全量快照(船队、航迹、最近事件) | | `ship` | 服务端→前端 | 每船最高 5 Hz 的增量补丁 | | `ships` | 服务端→前端 | 船队增删/上下线 | | `beat` | 服务端→前端 | 1 s 一次的心跳,带每船 `age_ms` / `online` | | `event` | 服务端→前端 | 告警(如 `obstacle_crit`) | | `cmd` | 服务端→前端 | 命令生命周期:`queued` / `accepted` / `rejected` / `timeout` | | `ping` / `resync` | 前端→服务端 | 心跳 / 请求重发全量 | 在线判定:`age < 8s` 在线;`8–30s` 迟滞(黄);`> 30s` 离线(灰,保留最后位置)。 --- ## 9. 错误码 统一响应体: ```json { "ok": false, "error": { "code": "bad_token", "msg": "设备密钥不正确" } } ``` | `code` | HTTP | 含义 | 船端怎么办 | | --- | --- | --- | --- | | `bad_token` | 401 | 缺头部或密钥错 | 不要猛重试,先查配置 | | `device_unknown` | 404 | 设备未注册 | 在 `config.json` 的 `devices` 里加,或开 `allow_unregistered` | | `bad_payload` | 422 | 字段缺失/类型错/JSON 坏 | 不改参数不要重试,看 `msg` | | `queue_full` | 429 | 该船命令队列满 | 说明上一条还没 ACK | | `not_online` | 409 | 船不在线(前端下发时报) | 船端看自己的上报是否在跑 | | `unsupported` | 409 | 该船不支持(如 2.4G 船开图传) | 不要重试 | | `expired` | 410 | 命令超 TTL | 由前端重新下发 | | `unknown_ship` | 404 | 找不到船 | 检查 id | | `internal` | 500 | 服务端异常 | 退避重试 | --- ## 10. 频率与流量预算 | 内容 | 建议频率 | 单帧大小 | 备注 | | --- | --- | --- | --- | | 位置/姿态(lat/lon/heading/sog/roll/pitch) | 5 Hz | ~120 B | 4G 下约 4.8 KB/s | | 电池/电压/电流 | 1 Hz | ~60 B | 走补丁,不重复发其它字段 | | `link`(信号、RTT) | 每 30 s | ~150 B | RTT 别每次都测 | | `obstacles` | 有变化就发,最快 5 Hz | ~80 B/个 | 障碍消失要发 `[]` | | `task` | 状态变化时 + 2 s 心跳 | ~120 B | | 合计 4G 下 ≈ **0.05 Mbps**,一天 ≈ 0.5 GB。**图传另算**(1400 kbps ≈ 15 GB/天,注意流量卡)。 服务端限流:单船遥测 ≤ 10 Hz,超了直接丢帧。 --- ## 11. 断线重连时序(照这个抄就行) ``` 上电 ├─ POST /device/hello → 校验密钥,拿 limits ├─ 循环: │ ├─ POST /device/telemetry → 带 data + 拿 commands │ ├─ 有 commands → 逐条:校验 ttl → 执行 → POST .../ack │ └─ sleep(200ms) └─ 任何请求连续失败 3 次: ├─ 指数退避 1s → 2s → 4s → 8s → 15s(封顶,加 ±20% 抖动) └─ 恢复后重新 hello(seq 可以从 0 重来) ``` 要点: - **服务端不保存历史命令**,断网期间的命令不会补发。重连后以当前状态为准。 - 重连抓到的第一件事是 `hello`,不是遥测——避免 seq 冲突带来的丢帧。 - 上报用 HTTP keep-alive;不要每次新建连接(4G 上握手很贵)。 --- ## 12. 2.4G 基站链路(以后扩展) 规划中的拓扑:`船 ──2.4G──► 船载基站 ──4G/有线──► 服务器`。 对服务端**没有区别**,仍然是同一套 `/api/v1/device/*`,只是: 1. 由**基站**代船上报,`X-Device-Id` 用船的 id; 2. `link.type = "2.4g"`、**`link.has_video = false`**; 3. 图传相关命令(`video_start`)必须回 `unsupported`,控制台会显示"该链路无图传"而不是报错; 4. `rtt_ms` 记的是**船→基站→服务器**的端到端延迟,不是单跳。 一条船从 4G 切到基站链路时,下一帧把 `link` 整体换掉即可,控制台会自动切换显示。 --- ## 13. 自测清单(联调时按顺序打勾) ```bash # 1. 握手 curl -X POST http://127.0.0.1:8099/api/v1/device/hello \ -H "X-Device-Id: usv-01" -H "X-Device-Key: vulpecat-dev-key" # 2. 上报一帧 curl -X POST http://127.0.0.1:8099/api/v1/device/telemetry \ -H "Content-Type: application/json" \ -H "X-Device-Id: usv-01" -H "X-Device-Key: vulpecat-dev-key" \ -d '{"v":1,"type":"telemetry","dev":"usv-01","seq":1,"ts":1794897971435,"data":{"lat":31.20769,"lon":120.15612,"heading":92.4,"sog":2.2,"roll":-2.2,"pitch":1.5,"batt":82,"gps":{"fix":3,"sats":13,"hdop":0.8},"link":{"type":"4g","has_video":true,"rssi":-69,"rtt_ms":61},"task":{"state":"idle","idx":0,"total":0,"eta_s":0},"mode":"auto","armed":true}}' # 3. 打开 http://127.0.0.1:8099/console ,左侧应出现 usv-01 且在线 # 4. 在网页上点「选点去这里」→ 地图点一下 # 船端应在下一次 telemetry 响应里收到 goto,并回 ACK # 网页底部状态条应显示「船端已接受 xx ms」 # 5. 用 --link 2.4g 再起一条假船,点图传开关,应看到 unsupported ``` - [ ] 密钥错 → 401 `bad_token` - [ ] 漏 `lat` → 422 `bad_payload`(或控制台坐标显示 —) - [ ] `seq` 回退 → 帧被忽略,不报错(**先调 hello 再回退才会被重置**) - [ ] 命令超过 `ttl_ms` 才处理 → 回 `expired`,不执行 - [ ] 同一 `id` 重复投递 → 只执行一次 - [ ] `link.has_video=false` → 控制台显示"该链路无图传" - [ ] 停上报 10 s → 左侧变黄(迟滞);30 s → 灰(离线),位置保留 --- ## 14. 参考实现 两份参考实现,协议完全一样,任选一份照抄: | 文件 | 语言 | 依赖 | 适用 | | --- | --- | --- | --- | | `tools/fake_device.py` | Python | 仅标准库 | 先验证服务端/联调,不需要编译 | | `tools/fake_device.cpp` | C++17 | libcurl + nlohmann/json | 船端 C++ 接入的直接模板 | C++ 那份把「hello → 5Hz 上报 → 收命令 → TTL 校验 → 幂等 ACK → 退避重连」都写好了, 上真船只需要改 `read_sensors()`(换成读 GPS/IMU/电池)和 `step()`(换成你的控制律)。 Python 版跑法: ```bash python tools/fake_device.py --id usv-x --key vulpecat-dev-key \ --url http://127.0.0.1:8099 --lat 31.2060 --lon 120.1580 ``` 它做的事:2 Hz 上报、随机游走、接收 `goto/route/rth/hold/estop/arm/disarm/set_home`、 按 §7 回 ACK、`2.4g` 模式下拒绝图传命令。 --- ## 15. C++ 实现要点 协议本身跟语言无关(HTTP + JSON),C++ 完全能用。下面是把上面这些端点落到 C++ 时真正会卡住的地方: | 环节 | 推荐 | 说明 | | --- | --- | --- | | HTTP 客户端 | **libcurl**(板子上基本都有)或 cpp-httplib(单头文件) | 必须开 keep-alive(`CURLOPT_TCP_KEEPALIVE`),4G 上每次新建连接握手很贵 | | JSON | nlohmann/json(单头文件、好写)或 cJSON / RapidJSON(省内存) | Rock 4D 这种 1~2GB 内存的板子用 nlohmann 没压力;MCU 类另说 | | 时间 | `std::chrono::system_clock` → 毫秒,用 `int64_t` | 别用 `int`(2038 年溢出,而且 ms 时间戳本身就超 32 位) | **六个具体的坑:** 1. **长轮询超时**:`GET /device/commands?wait=20` 会挂 20 秒,curl 的 `CURLOPT_TIMEOUT` 必须设成 **25~30 秒**。 用默认 60 秒也行,但如果设成 5 秒,你会以为服务端不回命令。 2. **`seq` 重启归零**:进程重启 / 看门狗复位后,**先调 `/device/hello`**(服务端会重置基线), 否则新帧全被当乱序丢掉,看起来就是"请求都 200,但船一直离线"。 3. **locale 坑**:任何 `setlocale(LC_ALL, "")` 之后再 `sprintf("%.6f")`,小数点可能变成逗号, 服务端直接 422。用 `std::to_chars`,或者别动 locale。 4. **浮点精度**:坐标保留 6 位小数就够(≈0.11 m),别把 `double` 的 15 位全发上来。 5. **ACK 幂等缓存**:至少存最近 32 个 `cmd.id` 的执行结果,重复投递直接重发上次 ACK。 用 `std::deque` + `std::unordered_map` 就够。 6. **过期不执行**:`now_ms - cmd.ts > cmd.ttl_ms` 直接回 `rejected/expired`。别嫌麻烦—— 断网几分钟后恢复,会把积压的"去这里"一次性推下来。 **线程结构(最简可行)** ```cpp // 单线程就够:遥测响应里带命令 while (running) { auto cmds = post_telemetry(build_frame()); // 5Hz for (auto &c : cmds) { if (accept(c)) execute(c); ack(c); } sleep_until(next_tick); // 200ms } // 想解耦就开两个线程:一个 5Hz 上报,一个 wait=20 长轮询收命令。 // 两条通道不会重复投递,但 ACK 仍要按 id 幂等。 ``` **HTTPS**:现在服务端是 `http://47.93.176.16:8446`,plain HTTP。以后套了 TLS, libcurl 记得给 `CURLOPT_CAINFO`(或 `/etc/ssl/certs`),别图省事关掉校验。 **先跑通再省流量**:`data` 支持稀疏补丁,但**第一版建议每帧发全量**, 确认整条链路(坐标、姿态球、命令)都对了,再把慢变量拆成 1Hz 补丁。 --- ## 16. 变更记录 | 版本 | 日期 | 变化 | | --- | --- | --- | | v1.1 | 2026-11 | `/device/hello` 会重置 `seq` 基线(设备重启不再被丢帧);补 C++ 实现要点 | | v1 | 2026-11 | 首版:HTTP 上行、命令 + ACK、稀疏补丁、无图传链路 |