operator
像控制台值班员，负责看面板、发命令、做管理动作。
Gateway 导读
WebSocket 握手决定你是谁：角色、作用域、能力
所有客户端（CLI、UI、节点）都通过同一个 WebSocket 端口连接，但握手时声明的 role 和 scopes 决定了你是操作员还是节点、能干什么。最容易错的是：节点必须声明 caps（摄像头、屏幕等），操作员则通过 scopes 控制读写权限——两者在 connect 请求里结构完全不同。
先讲这一页到底在解决什么
WebSocket 握手决定你是谁：角色、作用域、能力
所有客户端（CLI、UI、节点）都通过同一个 WebSocket 端口连接，但握手时声明的 role 和 scopes 决定了你是操作员还是节点、能干什么。最容易错的是：节点必须声明 caps（摄像头、屏幕等），操作员则通过 scopes 控制读写权限——两者在 connect 请求里结构完全不同。
第一步
🚪 第一个包必须是 connect，像进门先报到
官方把这件事写得很严格：第一帧必须是 connect。不先报到，门就不会正式打开。
Gateway 先发 challenge
像门卫先递出一张带时间戳和随机数的小纸片，确认你不是假冒来敲门。
Client 再回
connect像你把自己的身份、版本、角色、权限、设备签名都填在报到表上递回去。
hello-ok像门卫盖章：“好，进吧。你今天用协议 3，这里是值班规则。”
🎈 记一句
这不是“先随便连上再说”，而是“先过门卫，再拿通行牌”。
角色与权限
🪪 role 像工种，scope 像门卡权限
这是整页最核心的分野。只看一个不够，两个要一起看。
node
像带着摄像头、屏幕、定位这些能力在外面跑的小设备。
operator.read / write / admin / approvals / pairing
像不同颜色的门卡。读得到，不一定写得到；能操作，不一定能批敏感动作。
caps / commands / permissions
节点连进来时，会先报“我会什么”“我声称能做什么”“哪些开关已经打开”。
消息格式
✉️ 后面的纸条只有三种：请求、回应、广播
官方把 framing 写成结构体。换成人话，就是三种信封。
{type:"req"}像“我要办一件事”的申请单。
{type:"res"}像门卫回你的回执：办成了还是没办成。
{type:"event"}像广播喇叭，不是你问了才说，而是系统主动告诉大家“发生了一件事”。
idempotency keys
副作用动作要带幂等钥匙，像在申请单上写唯一流水号，防止同一张单子被误办两次。
命令翻译
📦 那个长长的 connect JSON，到底在现场讲了什么？
如果把字段逐个翻成人话，它就不再像一坨硬代码。
minProtocol / maxProtocol像说“我会的暗号版本最低到这里，最高到这里，你和我能不能对上号？”
client.id / version / platform / mode像在胸牌上写清“我是 CLI 还是 iOS 节点，我来自哪台机器，我今天是哪种模式上岗”。
auth.token像把门卡递给门卫看一眼，没有它就别想过闸。
device.publicKey / signature / nonce像除了门卡，还要出示设备自己的身份证明，证明你真是那台已经登记过的设备。
认证与设备令牌
🎟 第一次过门后，Gateway 还会发你一张“设备专属回头票”
官方这里很重要：配对后会发 device token。它像以后再次来访时更顺手的专属门票。
hello-ok.auth.deviceToken
像门卫说：“以后你这台设备再来，拿这张专属票就行。”
rotate / revoke
像门票丢了、要换新、或要作废时，可以专门去门卫室操作。
AUTH_TOKEN_MISMATCH
像普通门卡不对时，可信客户端可以小心地再试一次自己留存的设备票，但不能无限乱撞。
一句话
第一次是正式登记，以后则尽量靠设备专属回头票更顺地进门。
最后总结
🎈 把这页压成一句最短的话
Gateway Protocol 讲的就是门口怎么打招呼、纸条怎么写、门卡怎么验、以及不同工种到底被允许做什么：先握手，再报身份，再按统一信封格式收发消息。
如果你想看“门外这些客户端最终都怎么沿路回到总机房”，上一页就是 /gateway/network-model。