Skip to content

Presence ​

Moltbot 的 “presence” 是一个轻量、best‑effort 的视图,用来展示:

  • Gateway 自身,以及
  • 连接到 Gateway 的客户端(mac app、WebChat、CLI 等)

Presence 主要用于渲染 macOS app 的 Instances 标签页,并为操作者提供快速可见性。

Presence 字段(展示什么) ​

Presence 条目是结构化对象,常见字段包括:

  • instanceId(可选但强烈推荐):稳定的客户端身份(通常来自 connect.client.instanceId)
  • host:更友好的主机名
  • ip:best-effort 的 IP 地址
  • version:客户端版本字符串
  • deviceFamily / modelIdentifier:硬件提示
  • mode:ui、webchat、cli、backend、probe、test、node 等
  • lastInputSeconds:距离上次用户输入的秒数(若可用)
  • reason:self、connect、node-connected、periodic 等
  • ts:最后更新时间戳(epoch 毫秒)

生产者(presence 从哪里来) ​

presence 条目可能由多个来源产生,并会被 merged。

1) Gateway self entry ​

Gateway 启动时总会先写入一条 “self” 条目,让 UI 即使在没有客户端连接时也能显示 gateway host。

2) WebSocket connect ​

每个 WS client 都以 connect 请求开始。握手成功后,Gateway 会为该连接 upsert 一条 presence 条目。

为什么一次性的 CLI 命令不会显示 ​

CLI 经常为短暂的一次性命令而连接。为避免刷屏 Instances 列表,client.mode === "cli" 不会生成 presence 条目。

3) system-event beacons ​

clients 可以通过 system-event method 发送更丰富的周期性 beacon。mac app 用它上报 host name、IP 与 lastInputSeconds。

4) Node connects(role: node) ​

当 node 通过 Gateway WebSocket 以 role: node 连接时,Gateway 会为该 node upsert 一条 presence 条目(与其他 WS clients 的流程相同)。

合并 + 去重规则(为什么 instanceId 很关键) ​

presence 条目存储在单个内存 map 中:

  • 每条记录使用一个 presence key。
  • 最佳 key 是稳定的 instanceId(来自 connect.client.instanceId),可跨重启保持一致。
  • keys 不区分大小写。

如果 client 重连时没有稳定的 instanceId,它可能会显示为重复行。

TTL 与大小上限 ​

presence 有意保持“短暂”:

  • TTL:超过 5 分钟的条目会被清理
  • 最大条目数:200(优先丢弃最旧的)

这能保持列表新鲜并避免内存无限增长。

Remote/tunnel 注意事项(loopback IP) ​

当 client 通过 SSH tunnel / 本地端口转发连接时,Gateway 可能会把远端地址看成 127.0.0.1。为避免覆盖 client 自报的真实 IP,loopback 的 remote addresses 会被忽略。

消费方(Consumers) ​

macOS Instances 标签页 ​

macOS app 会渲染 system-presence 的输出,并基于最后更新时间的“年龄”应用一个小状态指示(Active/Idle/Stale)。

排查建议(Debugging tips) ​

  • 查看原始列表:对 Gateway 调用 system-presence。
  • 如果出现重复:
    • 确认 clients 在握手中发送稳定的 client.instanceId
    • 确认周期性 beacons 使用相同的 instanceId
    • 检查连接派生条目是否缺失 instanceId(此时重复是预期行为)