跳到主要内容

在线状态 (Presence)

Clawdbot 的“在线状态 (presence)”是一个轻量级的、尽力而为的视图，展示了：

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

在线状态主要用于渲染 macOS 应用的 “实例 (Instances)” 选项卡，并为操作员提供快速的可见性。

在线状态字段 (显示的属性)​

在线状态条目是结构化的对象，包含以下字段：

  • instanceId（可选，但强烈建议）：稳定的客户端身份（通常是 connect.client.instanceId）
  • host：易于阅读的主机名
  • ip：尽力而为获取的 IP 地址
  • version：客户端版本字符串
  • deviceFamily / modelIdentifier：硬件提示
  • mode：ui、webchat、cli、backend、probe、test、node 等
  • lastInputSeconds：“自上次用户输入以来的秒数”（如果已知）
  • reason：self、connect、node-connected、periodic 等
  • ts：最后更新时间戳（自纪元以来的毫秒数）

生成源 (在线状态从何而来)​

在线状态条目由多个来源生成并进行合并。

1) 网关自注册条目 (Gateway self entry)​

网关在启动时始终会播种一个“self”条目，以便在任何客户端连接之前，UI 就能显示网关主机。

2) WebSocket 连接​

每个 WS 客户端都以 connect 请求开始。握手成功后，网关会为该连接插入或更新 (upsert) 一个在线状态条目。

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

CLI 通常连接以执行简短的一次性命令。为了避免“实例”列表产生垃圾信息，client.mode === "cli" 不会被转换为在线状态条目。

3) system-event 信标​

客户端可以通过 system-event 方法发送更丰富的定期信标。macOS 应用使用此方法来报告主机名、IP 和 lastInputSeconds。

4) 节点连接 (role: node)​

当一个节点通过网关 WebSocket 以 role: node 连接时，网关会为该节点插入或更新一个在线状态条目（流程与其他 WS 客户端相同）。

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

在线状态条目存储在一个内存映射 (map) 中：

  • 条目通过在线状态键 (presence key) 进行索引。
  • 最好的键是稳定的 instanceId（来自 connect.client.instanceId），它在重启后依然保持不变。
  • 键不区分大小写。

如果客户端在没有稳定 instanceId 的情况下重新连接，它可能会显示为重复行。

生存时间 (TTL) 和容量限制​

在线状态是有意设计为临时性的：

  • TTL：超过 5 分钟未更新的条目将被修剪。
  • 最大条目数：200 条（达到上限后将丢弃最旧的条目）。

这可以保持列表的新鲜度，并避免内存无限制增长。

远程/隧道说明 (回环 IP)​

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

消费者​

macOS “实例 (Instances)” 选项卡​

macOS 应用渲染 system-presence 的输出，并根据最后一次更新的时间应用一个小状态指示器（活跃/空闲/陈旧）。

调试提示​

  • 要查看原始列表，请对网关调用 system-presence。
  • 如果您看到重复项：
    • 确认客户端在握手时发送了稳定的 client.instanceId
    • 确认定期信标使用相同的 instanceId
    • 检查源自连接的条目是否缺少 instanceId（此时出现重复是预料之中的）