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（此时重复是预期行为）