线路协议

本文是 agent、exchange、cli 三端之间线路格式的完整规格。定义位于 crates/proto，三端共享同一份代码——任何字段增删只有一处定义，不一致会在编译期而非某次线上会话中暴露。

面向两类读者：需要抓包排查问题的运维人员，以及要改协议或写第三方客户端的开发者。

目录

• 总览
• 传输与端点
• 协议版本
• 控制消息
  • DeviceUp（agent → exchange）
  • DeviceDown（exchange → agent）
  • OperatorUp（cli → exchange）
  • OperatorDown（exchange → cli）
  • 公共数据结构
• 二进制数据帧
• 会话编号的双空间翻译
• 握手时序
• 错误处理与失败分类
• 保活与超时
• 背压
• Android 屏幕控制
• 端到端密封会话

总览

协议分两层，复用同一条 WebSocket 连接：

分开的理由：流式数据经 base64 塞进 JSON 会膨胀约 33%，而 PTY 是逐键回显的高频小包，这部分开销直接体现为交互延迟。控制消息本身低频，JSON 的可读性（抓包能直接看懂）收益更大。

一个 WebSocket 二进制帧按约定只承载一个数据帧——多余或缺失字节都视为错误。

传输与端点

两条路径对应两类互不通用的凭证。设备令牌无法用于运维端点，反之亦然。

运维凭证走请求头而非 URL 查询串，因为 URL 会出现在反向代理日志、浏览器历史与 Referer 里。设备令牌走首帧而非请求头，是因为 WebSocket 握手头在某些嵌入式客户端上不易自定义，且首帧方案让「协议版本不匹配」和「令牌错误」能用同一条应答消息统一表达。

生产环境必须使用 wss://：两种凭证都以明文出现在握手阶段。

协议版本

pub const PROTOCOL_VERSION: u16 = 1;

版本在握手时双向比对，不匹配立即拒绝并给出明确提示。这样做是为了避免版本错配表现为「之后某条消息莫名其妙解析失败」——那种故障极难定位。

• 设备侧：agent 在 register 里带上自己的版本；服务端不匹配时回一条 ok: false 的 register_ack，error 字段说明双方版本，随后关闭连接。
• 运维侧：服务端连接建立后主动发 welcome，CLI 比对不一致时报错并提示升级到与 server_version 匹配的版本。

未知的消息 type 一律拒绝，不会被静默当成某个已知类型处理。

控制消息

所有控制消息都是 JSON 对象，用 type 字段做标签（serde 的 internally-tagged 枚举），标签值与字段名均为 snake_case。session_id 透明序列化为裸数字。

DeviceUp（agent → exchange）

服务端收到已注册连接上的第二条 register 会视为协议误用并记录告警。

示例：

{"type":"register","protocol_version":1,"device_id":"lab-router","token":"a1b2….c2Vj…","info":{"hostname":"OpenWrt","model":"ath79/generic","openwrt_version":"OpenWrt 23.05.5","kernel":"5.15.137","arch":"mips","agent_version":"0.1.0"}}
{"type":"exec_exit","session_id":31,"code":0,"timed_out":false}

DeviceDown（exchange → agent）

OperatorUp（cli → exchange）

鉴权在 WebSocket 握手阶段完成，因此没有登录类消息。

四条 open_* 消息里的 session_id 由 CLI 自己分配（见会话编号的双空间翻译），因此发出请求后可以立刻发后续帧，不必等编号回执。

OperatorDown（exchange → cli）

公共数据结构

ExecHoldInfo：job_id、kind（exec / download / upload / file）、age_secs、session_id?、command_preview、status、timeout_secs、started_at_unix_ms、exit_code?、timed_out。kind 缺省兼容为 exec，age_secs 缺省为 0；列表响应按当前时钟计算年龄。命令/文件路径摘要最多约 120 字符。非 exec 作业只能 kill，不能 tail/cat/attach。

DeviceSessionInfo：session_id: u32（设备侧编号）、operator_session_id: u32、kind: string、hold: bool、age_secs: u64、deadline_unix_ms: u64。会话列表/强制取消直接由 Exchange 回答，不向设备新开会话；只读账号返回 forbidden。

DeviceInfo

设备静态信息，register 时上报一次，落库到 devices.info。除 agent_version 外全部可选——agent 在非 OpenWrt 环境（开发机、容器）上运行时这些来源大多不存在，此时应当照常注册而不是启动失败。缺省字段在序列化时被省略。

Metrics

每个心跳周期重新采集，只收集能从 /proc 直接读到、无需 fork 子进程的项目。任何单项读取失败都不会导致整体失败——丢一项指标远好过让心跳整个失败、进而被判定为设备离线。

InterfaceStats：{ name: string, rx_bytes: u64, tx_bytes: u64 }

二进制数据帧

 0        1                    5                    9
 +--------+--------------------+--------------------+
 |  kind  |     session_id     |    payload_len     |  payload (payload_len 字节)
 |   u8   |    u32 (大端)      |    u32 (大端)      |
 +--------+--------------------+--------------------+
 └──────────── 9 字节定长头 ────────────┘

流类型

agent 若在下行方向收到 ExecStdout / ExecStderr，会记录告警并丢弃——那说明对端实现有误。

设计说明

payload_len 与 WebSocket 自身的长度字段确实冗余。 保留它有两个理由：解码时能校验出截断（声明 11 字节却只给 5 字节必须被识破，而不是静默接受成一个短包），以及日后若需要改走裸 TCP，帧格式无需变动。

1 MiB 的载荷上限不是为了正常流量——PTY 与命令输出都是流式增量推送，远达不到这个量级——而是为了让对端无法用一个声称载荷 2 GiB 的帧头撑爆服务端内存。

空载荷是合法的：PTY 会话中偶尔会出现零字节读取。此时整帧就是 9 字节的头。

载荷是任意字节，包括非 UTF-8 序列，必须原样保留。

解码错误

数据帧解码失败只影响该帧：exchange 记录一条告警并丢弃，不会断开连接。

会话编号的双空间翻译

这是协议里最容易理解错的部分。

一句话概括

session_id 由发起方分配，且只在它自己那条连接内唯一。运维侧和设备侧各自维护一套独立的编号空间，exchange 在中间做翻译。同一个逻辑会话在两侧有两个不同的编号。

  remote-cli                    exchange                      remote-agent
                                                        （设备 lab-router）

  ┌────────────┐        ┌────────────────────┐            ┌────────────┐
  │ 运维编号   │        │      路由表        │            │ 设备编号   │
  │  空间      │        │                    │            │  空间      │
  │            │        │  lab-router:       │            │            │
  │  session 7 │───────▶│    31 → (op-A, 7)  │───────────▶│ session 31 │
  │            │◀───────│                    │◀───────────│            │
  └────────────┘        │  op-A:             │            └────────────┘
                        │    7 → (lab-router,│
   由 CLI 自己的        │         31)        │             由 exchange
   SessionIdGenerator   └────────────────────┘             的 DeviceHandle
   分配（1,2,3…）                                          分配（1,2,3…）

为什么要这样设计

避免一次往返。 如果编号由服务端统一分配，CLI 打开 PTY 后必须先等一条「你的会话编号是 31」的回执，才能开始发键盘输入。让 CLI 自己分配，open_pty 发出去的下一刻就能发数据帧。

避免跨运维端的编号冲突。 两个不同的运维人员完全可能同时用本地编号 1 去操作同一台设备。设备侧必须能区分它们，否则一个人的输出会流向另一个人。exchange 为每条设备连接单独分配设备侧编号，两个 session 1 会被映射成设备侧的 31 和 32。

避免设备侧编号被运维端行为影响。 设备侧的编号完全由 exchange 掌控，任何运维端都无法指定或猜测。

两张表

exchange 为每条连接维护一张表，两张表始终成对更新：

反向索引存在的意义是清理：运维端断开时，要能找到它在各台设备上留下的会话并逐一终止，否则设备上会残留无人接收输出的进程和 PTY。

翻译发生在哪

数据帧的翻译是唯一的改写动作——exchange 不解析、不缓存、不修改任何一个载荷字节。DataFrame::with_session_id 就地替换而不重新分配载荷。

分配规则

两侧的分配器都从 1 开始递增，跳过 0（0 是「不属于任何会话」的哨兵，例如连接级错误消息）。

• CLI 侧（SessionIdGenerator）：溢出后回绕并跳过 0。单条连接内用满 40 亿个会话不现实，但回绕比 panic 更符合长驻进程的需要。
• 设备侧（DeviceHandle::open_session）：回绕后若撞上仍存活的旧会话，继续找下一个空位。

exchange 拒绝运维端使用 0 或重复使用仍在活动中的会话编号。设备连接有效性、并发上限和两侧索引的登记在同一临界区内检查，避免多个运维连接同时打开会话时突破上限。

查不到路由时的行为

静默丢弃，不报错。 会话刚被关闭而对端还在发尾巴上的数据，属于正常竞态。这条规则对两个方向都成立：

• 设备回复了一个已不存在的会话 → 记 debug 日志，可能是运维端先行断开
• 运维端发来无主会话的数据 → 记 trace 日志并丢弃

会话的清理路径

反向索引绑定具体的设备连接，不会在设备重连后按设备 ID 转向新连接。同一账号的多个运维连接分别持有自己的索引，断开其中一个不会取消另一个连接的会话。

主动取消的结束回执：exec 返回 exec_exit（code: null、timed_out: false），PTY 返回 pty_closed（code: null），ubus 返回 session_failed（reason: device_error）。这是 exchange 确认会话已关闭，不是远端进程已经退出的证明；设备后续返回的尾部数据和退出消息会被丢弃。

达到并发上限时，Exchange 在同一会话锁下先回收失去运维端或超过截止时间的路由，再重新检查上限。exec 截止时间为实际下发时限加 15 秒宽限；文件为 3600 秒加 15 秒；其它类型为 24 小时。截止时间内的 hold exec 不因运维端离开而被杀。回收/显式 kill_device_session 会向设备发对应取消指令并立即删除两侧索引，无需设备回复；可用运维端收到 exec 的 exec_exit（timed_out:true）或其它类型的 session_failed（device_error、session reclaimed），审计尽力异步回填。

设备重连与 epoch

每条设备连接在注册时会拿到一个随机的 epoch（UUID）。同一设备再次连入时，新连接顶替旧连接——而不是拒绝新连接，因为无法可靠区分「重复连接」与「旧连接已死但服务端还没发现（半开连接）」，拒绝会让设备在旧连接超时前一直连不上。

旧连接的清理逻辑可能晚于新连接的注册才执行。因此注销时必须校验 epoch：只有当连接表里当前那条连接的 epoch 与自己一致时才真的移除。少了这道校验，刚上线的设备会被旧连接的清理逻辑立刻标记为离线。

握手时序

设备侧

  remote-agent                                        exchange
      │                                                 │
      │  ①  WebSocket 握手（wss://host/ws/device）      │
      │────────────────────────────────────────────────▶│
      │◀────────────────────────────────────────────────│
      │            101 Switching Protocols              │
      │                                                 │
      │                                          ┌──────┴──────┐
      │                                          │ 启动 15 秒  │
      │                                          │ 注册计时器  │
      │                                          └──────┬──────┘
      │  ②  {"type":"register","protocol_version":1,    │
      │      "device_id":"…","token":"…","info":{…}}    │
      │────────────────────────────────────────────────▶│
      │                                                 │
      │                              ┌──────────────────┴──────────────────┐
      │                              │ a. 比对 protocol_version            │
      │                              │ b. split_token → 前缀查 devices 表  │
      │                              │ c. 校验 enabled                     │
      │                              │ d. argon2 verify（前缀不符也照做，  │
      │                              │    避免用耗时区分前缀是否存在）     │
      │                              └──────────────────┬──────────────────┘
      │                                                 │
      │  ③  {"type":"register_ack","ok":true,           │
      │      "error":null,"heartbeat_interval_secs":30} │
      │◀────────────────────────────────────────────────│
      │                                                 │
      │                                          ┌──────┴──────┐
      │                                          │ 登记连接表  │
      │                                          │ 顶替旧连接  │
      │                                          │ 回写 info 与│
      │                                          │ last_seen_at│
      │                                          └──────┬──────┘
      │                                                 │
      │  ④  退避曲线复位，写状态文件 state=connected     │
      │                                                 │
      │══════════════ 转发循环 ═══════════════════════════│
      │                                                 │
      │  heartbeat（每 30 秒，携带 Metrics）             │
      │────────────────────────────────────────────────▶│
      │  WebSocket Ping（随每次 heartbeat 发出）         │
      │────────────────────────────────────────────────▶│
      │                                     WebSocket Pong
      │◀────────────────────────────────────────────────│
      │                                     WebSocket Ping（每 30 秒）
      │◀────────────────────────────────────────────────│
      │  Pong（tungstenite 排队，agent 显式 flush）       │
      │────────────────────────────────────────────────▶│

失败路径：

• 首帧不是文本帧、不是合法 JSON、或不是 register → 记录告警，直接关闭连接（不发 ack）
• 15 秒内未发出 register → 关闭连接
• 版本不匹配 → 回 register_ack{ok:false, error:"协议版本不匹配：设备为 X，服务端为 Y"}，关闭
• 令牌无效 / 设备不存在 / 设备已停用 → 一律回同一句 "设备 ID 或令牌无效"，关闭。不区分原因：区分开会把设备清单变成可枚举的信息

agent 侧把这两类失败分开处理：

退避曲线只在注册成功后才复位，而不是 TCP 一建立就复位。否则遇到「连上即被拒」的情况会退化成毫秒级的密集重试。

抖动不是锦上添花。 服务端重启时成百上千台设备会在同一瞬间检测到断连，若都按同一条确定性曲线重连，它们会保持同步、成批次冲击刚起来的服务端，把一次重启放大成持续的雪崩。

运维侧

  remote-cli                                          exchange
      │                                                 │
      │  ①  WebSocket 握手（wss://host/ws/operator）    │
      │      Authorization: Bearer <prefix>.<secret>    │
      │────────────────────────────────────────────────▶│
      │                                                 │
      │                              ┌──────────────────┴──────────────────┐
      │                              │ 在 upgrade 之前完成鉴权：           │
      │                              │ split_token → 前缀查 operators 表   │
      │                              │ → argon2 verify → 校验 enabled      │
      │                              └──────────────────┬──────────────────┘
      │                                                 │
      │      鉴权失败 → HTTP 401「凭证无效」（不升级）   │
      │◀────────────────────────────────────────────────│
      │                                                 │
      │◀────────────────────────────────────────────────│
      │            101 Switching Protocols              │
      │                                                 │
      │  ②  {"type":"welcome","protocol_version":1,     │
      │      "server_version":"0.1.0"}                  │
      │◀────────────────────────────────────────────────│
      │                                                 │
      │  ③  比对 protocol_version（15 秒超时）          │
      │      不一致 → 报错退出，提示升级 CLI            │
      │                                                 │
      │══════════════ 可以发起会话 ═══════════════════════│
      │                                                 │
      │  {"type":"open_pty","session_id":1,             │
      │   "device_id":"lab-router","rows":40,"cols":120}│
      │────────────────────────────────────────────────▶│
      │                                                 │──▶ 查设备在线
      │                                                 │──▶ 查并发上限
      │                                                 │──▶ 查 readonly 角色
      │                                                 │──▶ 写审计（先于下发）
      │                                                 │──▶ 分配设备侧编号
      │  二进制帧（PtyData, session 1, 键盘输入）        │
      │────────────────────────────────────────────────▶│──▶ 改写为设备侧编号
      │                                                 │
      │  二进制帧（PtyData, session 1, 屏幕输出）        │
      │◀────────────────────────────────────────────────│◀── 改写为运维侧编号

注意 CLI 不必等待任何确认就能发出第二步的数据帧——这正是让发起方分配编号的意义。

错误处理与失败分类

SessionFailure

出现在 session_failed 消息的 reason 字段，JSON 值为 snake_case。

is_retryable() 的分类刻意把 forbidden 和 device_error 排除在外——重试一个权限问题或设备内部错误没有意义，只会让 CLI 空转。

CLI 收到后会在原始 message 之后追加一句可操作的提示，例如 device_offline 会提示用 remote-cli device list 确认设备状态。device_error 例外——设备侧的错误信息本身就是最准确的说明，不该被套话稀释。

分层的失败语义

原则是：能局部化的失败绝不上升为连接级故障，因为一条设备连接上可能同时跑着多个运维人员的会话。

保活与超时

空闲 shell 的客户端仍会回复 Pong；agent 通过显式 flush 发出库自动排队的应答，不必等下一次业务心跳，因此不会因没有键盘输入而被判定失联（#42）。--heartbeat-secs 必须大于 0，非法值在启动参数解析时被拒绝。

背压

exchange 为每条连接维护一个容量 512 条消息的有界发送队列。

队列写满意味着对端消费速度已经跟不上——PTY 会话里通常是网络卡死或客户端挂起。此时的处理是主动断开该连接，而不是继续缓冲：无界缓冲会把一个卡住的客户端变成整个服务的内存泄漏。512 条对交互式 PTY 是很大的余量（正常情况下队列长度是个位数），触及上限基本可以断定对端已经不再消费。

投递一律用非阻塞的 try_send。路由路径上持有着连接表的锁，任何 await 都会把锁的持有时间和对端的消费速度绑在一起，一个慢客户端将直接拖住整张表。

两种投递失败被区分对待：

连接关闭信号不经过发送队列，队列满或写入阻塞时仍能触发清理；设备重连顶替和令牌轮换使用同一机制。

agent 侧同样有一个容量 256 的出站队列。队列满说明网络已经完全送不出数据，此时继续堆积没有意义，应当断开重连。PTY 的输入队列（64）满时直接丢弃按键——交互式的小数据堆积起来没有意义。

Android 屏幕控制

定义位于 crates/proto/src/android.rs，使用现有双空间会话路由、鉴权、并发限制和审计。open_android / android_req 的 request 是由 action 区分的 JSON 对象：

AndroidResult 由 kind 区分，字段均为必填：

节点包含字符串 class_name, package, view_id, text, description，bounds: [left, top, right, bottom]（有符号屏幕像素坐标），以及布尔字段 clickable, editable, focused, password。最多 200 个节点，每个字符串最多 256 个 UTF-16 单元；truncated 仅标记节点上限。密码值和描述为空，agent 自身配置子树被省略。

截图长边最多 1600 像素；width/height 是图像尺寸，screen_width/screen_height 是缩放前尺寸。手势坐标按缩放前尺寸处理。Java 桥接返回 JSON 最多 2 MiB，WebSocket 封装额外允许 1024 字节。没有新增二进制帧类型。

{"type":"open_android","session_id":1,"device_id":"phone","request":{"action":"input_text","text":"Hello\nWorld"}}
{"type":"android_req","session_id":31,"request":{"action":"input_text","text":"Hello\nWorld"}}
{"type":"android_resp","session_id":31,"result":{"kind":"ok"}}
{"type":"android_resp","session_id":1,"result":{"kind":"ok"}}

screen_capture_enabled 表示当前有可用截图授权（MediaProjection，或 Android 11+ 辅助功能）；所有实际屏幕操作仍要求 controls_enabled。权限不足、窗口不可访问或操作失败由 agent 返回 session_error，Exchange 转为 session_failed。非 Android agent 返回明确的不支持错误。

Agent 最多同时处理 4 个 Android 请求，同一时刻只编码一张截图。Java 操作等待最多 10 秒（等待屏幕帧最多 5 秒），agent 请求超时为 15 秒，CLI 为 20 秒。运维取消或断开时 Exchange 下发 android_cancel；agent 关闭本地 socket，APK 取消尚未执行的排队工作。已执行的手势或文本修改不会回滚。

审计 action 为 android，detail 保存动作及坐标；input_text 只保存 characters（Unicode 字符数），成功结果只记 outcome: "completed"。正文、界面树和图像不写入审计。readonly 账号连 status、tree 和截图也不能发起。

文件会话扩展

支持文件操作的 Agent 声明 files 能力。open_file {session_id, device_id, request} 经 Exchange 翻译为 file_req {session_id, request}；request.action 为 list、download 或 upload，字段定义见 crates/proto/src/files.rs。

双向控制消息采用 JSON：控制端发送 file_input {session_id, input}，设备返回 file_event {session_id, event}。input.kind 为 chunk {offset, data}、ack {offset} 或 finish，event.kind 为 ready {size}、chunk {offset, data}、progress {received}、complete {size} 或 list {path, entries, truncated}。块内容使用标准 Base64；每块最多 64 KiB，发送方等待确认后继续。

下载的第一条 ready 需要 ack {offset: 0}，随后每块确认累计字节数。上传从 ready 开始，由每条 progress 驱动下一块，全部发送后用 finish 提交。complete 和 list 为终结消息，错误使用现有 session_error / session_failed。close_session 下发 file_cancel，取消和断线均移除会话路由。文件消息只在文件会话上转发，保持操作员会话 ID 与设备会话 ID 的隔离。

协议版本仍为 1；新增消息需要配套升级 Exchange 和 Agent。操作限制及 LAN 接口见 文件传输与局域网直连。

多平台扩展

协议版本仍为 1。注册的 info 新增可选 platform（openwrt / linux / freebsd / netbsd / windows / android / macos）、os_version、capabilities（exec / pty / ubus / android_control / files / sensors / net）。OpenWrt 上报 openwrt_version。

心跳 metrics.unavailable 是可选字符串数组，指出当前无法采集的 uptime、load、memory、cpu、interfaces。数组缺失按旧格式解析；列出的指标所对应数值只是兼容占位，客户端应显示缺项。Windows 不提供 Unix 平均负载，Android 的部分 /proc 来源可能被系统权限限制。

执行命令按目标设备的 shell 解释：Linux/OpenWrt/macOS 为 /bin/sh，Windows 为 PowerShell，Android 为 /system/bin/sh。PTY 帧格式与控制消息在三个系统上相同，Windows 使用 ConPTY。非 OpenWrt 设备收到 ubus 请求时返回 session_error。

端到端密封会话

协议版本仍为 1。新增消息：OperatorUp open_sealed {session_id, device_id, hello}、sealed_input {session_id, packet}；DeviceDown sealed_open {session_id, hello}、sealed_input、sealed_close {session_id, detach}；DeviceUp / OperatorDown sealed_accept {session_id, accept}、sealed_event {session_id, packet, last}。新增二进制帧类型 4 = Sealed（载荷 counter ‖ AEAD(inner_kind ‖ bytes)），DeviceInfo.seal_key 与能力 sealed。

Exchange 对密封会话只做编号翻译、并发限制和路由：不解析、不审计载荷（审计只记公钥、授权级别与到期、结束结果），不判定权限（只检查账号能否看到该设备），last:true 时释放路由。密封路由只接受 Sealed 帧，普通路由不接受 Sealed 帧；agent 丢弃任何发往密封会话编号的明文。授权、握手、密钥派生、威胁模型见 端到端密封会话。