使用教程 — Loomi

0. 先看清两个部件

部件	装在哪	作用
`loomi-plugin`	跑 Hermes 的那台机器	Hermes 平台适配器。在网关进程内起一个 WebSocket 服务，把 Agent 事件、审批请求与通知推给手机，并接收手机发来的动作。不修改 Hermes 核心。
Loomi App	Android 手机	注册进网关的一台设备。四个页面：任务、时间线、审批、设置。

环境要求：Hermes Agent（插件按 2026.9.24 源码验证）、Python aiohttp（Hermes 的 api_server 平台本来就依赖它，通常已装）、配对二维码需要 qrcode（首次运行 hermes loomi pair 会自动尝试安装，装不上时改用文本配对）。手机端 Android 8.0 以上。

1. 服务端：装插件

从下载页取插件包，解压后把目录放进 Hermes 的插件目录：

cp -r loomi-plugin ~/.hermes/plugins/

也支持用 hermes plugins install <git-url> 从仓库安装。

2. 服务端：启用与配置

hermes plugins enable loomi
hermes config set platforms.loomi.enabled true
hermes config set platforms.loomi.extra.host 127.0.0.1
hermes config set platforms.loomi.extra.port 8788

默认只绑 127.0.0.1，也就是只有本机能连。这是刻意的：手机要连，走反代或隧道终止 TLS 后接入，不要把网关端口直接暴露到公网。

3. 服务端：重启网关并自检

hermes gateway restart
hermes loomi status

重启会中断正在跑的会话，QQ / 微信这类通道会断十几秒，挑没人用的时候做。自检期望看到「服务运行中」以及协议地址 ws://127.0.0.1:8788。

4. 配对：一次扫码

hermes loomi pair

终端会打出二维码，手机 App 打开「配对」页扫码，自动换取设备凭据，此后不再需要扫码。令牌是一次性的，默认 300 秒过期；扫不到时可以把终端打印的那行 JSON 直接粘进 App 的输入框。

手机和服务器不在同一网段时，先设对外地址再配对（反代或隧道终止 TLS）：

hermes config set platforms.loomi.extra.public_url wss://hermes.example.com/ws

5. 手机端：四个页面

任务

每次 Agent 回合一条。状态为运行中、等待审批、已完成、失败、已取消；条目上带标题、工具调用次数与时间。有等待授权的条目时，页面顶部会显示「有 N 项等待你授权」，点进去直接处理。

时间线

按序号回放一个回合：流式输出、每一次工具调用与它的结果、耗时与成败。断线重连后接着看，序号去重，不重复也不漏帧。

审批

本机命令的授权请求会推到这里：命令原文、说明、超时时间与可选动作。策略判定为高风险的请求只给「放行一次」或「拒绝」两个出口。人在外面也能决定 Agent 能不能跑这条命令。

设置

连接信息（服务器地址、设备 ID、服务端版本、当前状态）、连接诊断（最新序号、已收帧数、重连次数、丢弃重复、与服务端时差、最近错误）、保活与通知开关，以及「重新连接」「忘记设备」。

6. 保活与通知

点「申请忽略电池优化」，把 Loomi 加入电池白名单。各厂商的省电策略会杀掉长连接，不加白名单就收不到推送。
「开机自动连接」默认开：设备重启后自动恢复长连接。
「任务完成静音」默认开：只有审批才响铃，避免每完成一个回合就震一次。
通知权限要在系统设置里给足，设置页有直达按钮。

7. 设备管理

hermes loomi devices            # 列出设备与在线状态
hermes loomi revoke dev_xxxx    # 撤销设备，即时踢下线
hermes loomi status             # 连接诊断

手机丢了或换机，直接撤掉那台设备的凭据，不用改任何其他配置。

8. 放到公网（反代要点）

反代必须支持 WebSocket Upgrade，并把空闲超时放到 60 秒以上（插件每 25 秒发一次心跳）：

location /ws {
    proxy_pass http://127.0.0.1:8788;
    proxy_http_version 1.1;
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection "upgrade";
    proxy_set_header Host $host;
    proxy_read_timeout 600s;
    proxy_send_timeout 600s;
}

不走反代、让插件自己终止 TLS 时：

hermes config set platforms.loomi.extra.tls_cert /path/fullchain.pem
hermes config set platforms.loomi.extra.tls_key  /path/privkey.pem

插件内置的安全约束不是建议：非回环地址且未配置 TLS 时适配器拒绝启动（要强行放开得显式设 LOOMI_ALLOW_INSECURE_BIND=true）；没有鉴权的 WebSocket 连接会在 10 秒内被服务端关闭； /internal/* 端点只接受回环来源。

9. 常见问题

手机一直显示「连接失败」或「重连中」。: 先看服务端 hermes loomi status 是否「服务运行中」；再确认 App 设置页里的服务器地址是不是 wss:// 开头的对外地址。反代的 proxy_read_timeout 低于 60 秒会被掐断，表现为连上几秒就掉。
扫码时提示令牌过期。: 配对令牌默认 300 秒有效且只能用一次。重新执行 hermes loomi pair 再扫。
审批通知不响。: 依次检查：系统通知权限、Loomi 是否在电池白名单、「任务完成静音」是否被自己关掉（这项影响的是完成通知，不影响审批）。
网关重启后时间线乱了。: 事件序号由网关进程内的计数器产生，网关重启后归零。App 在握手应答里比对服务端版本与截断标志，发现重启会重新拉取任务列表；不要跨重启比对序号。
能装多台手机吗？: 可以，每台手机各自配对。但一个网关进程只有一个 Loomi 适配器实例，多设备靠多台配对实现。
「暂停 / 继续」是完整的暂停吗？: 不是。Hermes 的回合无法真正挂起，v1 里「暂停」是软中断（等价 /stop），「继续」是向该会话注入一句「继续」。协议字段保留，界面文案如实标注。

10. 协议规范

手机与插件之间用 Loomi Protocol（LMP）v1，单条 WebSocket、JSON 帧、按序号去重与补发。完整字段表见 Loomi Protocol v1，其中也写明了配对流程、断线补发窗口与每条事件的载荷。