Presence

Moltbot “presence” 是轻量、尽力而为的视图：

• 网关本身，以及
• 连接到网关的客户端（mac 应用、WebChat、CLI 等）

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

Presence 字段

Presence 条目为结构化对象，含字段：instanceId（可选但强烈推荐，稳定客户端身份）、host、ip、version、deviceFamily/modelIdentifier、mode（ui、webchat、cli、backend、probe、test、node 等）、lastInputSeconds、reason、ts。

生产者（来源）

Presence 条目由多个来源产生并合并。

1) 网关自身条目

网关启动时始终播种”自身”条目，使 UI 即使无客户端连接也显示网关主机。

2) WebSocket 连接

每个 WS 客户端从 connect 请求开始。成功握手后网关为该连接 upsert presence 条目。

为何一次性 CLI 命令不显示

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

3) system-event 信标

客户端可通过 system-event 方法发送更丰富的周期性信标。mac 应用用此上报主机名、IP 与 lastInputSeconds。

4) 节点连接（role: node）

节点通过网关 WebSocket 以 role: node 连接时，网关为该节点 upsert presence 条目（与其他 WS 客户端相同）。

合并与去重规则（为何 instanceId 重要）

Presence 条目存储在单一内存映射中：

• 条目按 presence 键键控。
• 最佳键为跨重启保持的稳定 instanceId（来自 connect.client.instanceId）。
• 键不区分大小写。

客户端重连时若无稳定 instanceId 可能显示为重复行。

TTL 与有界大小

Presence 刻意为临时性：

• TTL：超过 5 分钟的条目被修剪
• 最大条目：200（超出时最旧的先丢弃）

保持列表新鲜，避免无界内存增长。

远程/隧道注意（回环 IP）

客户端通过 SSH 隧道/本地端口转发连接时，网关可能将远程地址视为 127.0.0.1。为避免覆盖客户端上报的好 IP，会忽略回环远程地址。

消费者

macOS Instances 标签页

macOS 应用渲染 system-presence 输出，并根据最后更新的年龄应用小型状态指示器（Active/Idle/Stale）。

调试建议

• 查看原始列表：对网关调用 system-presence。
• 若看到重复：确认客户端在握手中发送稳定 client.instanceId；确认周期性信标使用相同 instanceId；检查连接派生条目是否缺少 instanceId（重复在此情况下为预期）。