企业官网建设流程全解析

nanoMuse 是一个开源的个人 AI Agent（智能体），同一账号下可以在手机、电脑和浏览器中同时运行。它的跨设备Hub 协议让所有设备通过一根 WebSocket 连接互相发现、**委托任务（task）并把审批（approval）**卡片实时回传给发起方。本文带你完整读懂这套协议：6 种核心帧、审批回流机制、限速与重连策略，以及关键源码位置，零基础也能看懂。

一、为什么需要跨设备 Hub？📱💻

每款设备都有自己的"手"：

• 手机：App 与沙箱环境（读通知、发消息、操作界面）
• 电脑：shell 命令行、文件系统、屏幕截图
• 浏览器：没有自己的手，只是一扇"前门"

Hub 的价值在于：任何设备都可以请求任何设备干活，无论它们各自在什么网络里。比如在手机上说一句"在我 Mac 上列一下下载文件夹"，命令就会经 Hub 路由到电脑执行，结果原路返回——不需要共享 Wi-Fi，不需要端口转发。

二、整体架构：一根出站 WebSocket，谁都不用开端口 🔌

整个协议的设计极简，只有一个核心思想：

所有设备都主动向中继（relay）拨出一根 WebSocket 并保持长连；设备端不监听任何端口，中继只在同一账号的设备之间转发帧（frame），从不窥探任务内容。

手机 ──┐ ┌── 电脑 (nanoMuse Desktop) ├──▶ nanoMuse Cloud ◀───┤ 浏览器 ─┘ /v1/hub └── 另一台手机 / 电脑

• 连接地址为WS /v1/hub，鉴权用Authorization: Bearer nm_…（浏览器把 key 放在hello帧里，因为浏览器无法自定义请求头）
• 设备 id 按安装生成（phone-…、pc-…），同一 id 的新连接会替换旧连接（关闭码4003）
• 中继只记录设备名与最后在线时间，不存储你请求过什么——这是它的信任模型

三、六类核心 WebSocket 帧速览 ⚡

全部帧都是 JSON 文本。理解这 6 类帧，就读懂了 90% 的协议：

一次典型的call长这样：

{"type": "call", "id": "a1b2…", "to": "pc-9f3e", "action": "shell", "args": {"command": "ls ~/Downloads"}}

目标设备执行后回result；若执行较慢，会先连续发若干event帧报告进度，最后才发result。超时 15 分钟没人应答的call，中继会主动给发起方回timeout错误帧（CALL_TTL_S，见 cloud/nanomuse_cloud/hub.py）。

四、两种委托方式：原始动作 vs 整包任务 🤝

① 原始动作（Actions）——直接、即时：

info、shell、files、file.get、file.put、open、screen、notify（见 nanomuse/hub/actions.py）。截图和文件字节用 base64 装进帧里，单文件上限 8 MB。

② 整包任务（Task）——用一整段自然语言，交给目标设备自己的 Muse去办：

{"type": "call", "id": "c3d4…", "to": "phone-7a21", "action": "task", "args": {"text": "打开日历，告诉我明天第一场会议", "language": "zh-CN"}}

• conversation可选：命名这次委托的会话（缺省用发起方 id）
• language可选：发起方界面的 BCP-47 语言标签，目标 Muse 会用它作答而不是猜
• 任务最长可跑 15 分钟；在目标设备上，任务跑在一个可见的侧边聊天里，人可以随时围观、插话或按 Stop
• 发起方随时可用stop {call}中止——但任何设备都只能停自己发起的任务

五、审批如何跨设备回流？这是协议最妙的部分 ✨

任务在目标设备上跑到一半，如果碰到了需要人点头的操作（删文件、付款、外发数据），目标 Muse不会擅自决定，而是走一套"审批回流"流程：

1. 目标设备的 Sentinel（安全护栏）生成审批卡片
2. 以event帧发回给发起方：{stage:"approval", approval_id, preview, risk, reason, device, timeout}
3. 发起方在自己的界面弹出卡片（手机上是 RiskGate、终端里是提示符、网页上是一张卡片），由提问的那个人来拍板
4. 发起方把决定打包成approve {approval_id, allow}帧送回
5. 目标执行/拒绝，并把approval_result {approval_id, status}广播给两端，卡片同时关闭

三条关键规则（源码在 nanomuse/hub/service.py 的on_call分发器中）：

• 设备只能批准自己发起的运行所产生的卡片，不能批准"你允许我干吗"这类元审批
• 命令的风险在输入设备上判定（发出前），不依赖目标设备
• 反向操作同理：目标设备上的"远程遥控"开关（Remote control）关闭时，除info外一切请求都回not_allowed；shell等敏感动作首次请求还会弹出"一次 / 对该设备永久"的授权卡片

审批帧的发送端实现在 nanomuse/hub/service.py 的_forward_event，接收端在 nanomuse/hub/service.py 的decide_remote。

六、健壮性设计：错误码、限速与断线重连 🛡️

协议对"设备离线、网络抖动、恶意刷帧"都有明确预案：

关闭码（Close Codes）

错误帧：device_offline（目标不在线）、self_call（不能叫自己）、not_controllable（浏览器标签页不能被委托）、unknown_call（该 id 上没有等待中的调用）、too_large、rate_limited等，定义见 cloud/nanomuse_cloud/hub.py。

限速与心跳（cloud/nanomuse_cloud/hub.py）：

• 单 socket 持续限速60 帧/秒、8 MB/秒（令牌桶算法），突发翻倍；连续丢弃 600 帧直接4008关闭
• 单帧上限16 MB（HUB_FRAME_LIMIT）
• 客户端每25 秒发一次ping，20 秒无pong即认定网络已断（笔记本休眠、Wi-Fi 切换的"僵尸连接"由此被发现），退避重连：1 秒起步、指数翻倍、封顶 30 秒（nanomuse/hub/client.py）
• 发送永不等待对端：帧先入队按序写出，一台卡死的手机不会拖垮正在调它的电脑

七、核心源码导读 📚

想深入实现，按这条线读即可：

• 协议总文档（帧、错误码、信任模型全在这里）：docs/hub.md
• 任务如何旅行的流程图与跨端行为：docs/every-device.md
• 中继端路由（hello握手、_call转发、_answer回执、超时清扫）：cloud/nanomuse_cloud/hub.py
• 运行时端客户端（WebSocket 长连、退避重连、call出站）：nanomuse/hub/client.py
• 入站调用分发（approve/task/stop/ 原始动作）：nanomuse/hub/service.py
• task如何落成侧边聊天并回传事件流：nanomuse/hub/service.py
• Agent 视角的委托工具（devices、device_shell、delegate等 9 个工具）：nanomuse/tools/devices.py
• 协议测试（用假中继验证全链路）：cloud/tests/test_hub.py

八、小结：这套协议教会我们的三件事 💡

1. 只出站、不监听：一根 WebSocket 长连解决了移动设备"无法被访问"的千古难题
2. 中继只管路由，判定留在端上：风险在输入设备判定、审批由提问者拍板，云端信任面被压到最小
3. 一切皆帧，帧皆可回放：任务进度以event帧流式回传，发起方看到的体验与在目标设备上亲眼看完全一致

读懂这 6 类帧和审批回流，你就掌握了 nanoMuse 跨设备协作的全部骨架。