跳转至

会话状态感知

多个会话经常协同处理同一个问题。例如,管理者将任务委派给子会话、人类直接切入某个工作会话,以及两个代理通过 sessions_send 进行协调。每个会话都会建立关于其他会话的假设。一旦另一个参与者介入,这些假设就会失效。会话状态感知(session state awareness)就是检测这种介入的机制。它会向受影响的会话通知一次,然后为该会话提供一种低成本的方式,在采取行动之前追平状态。

三个部分协同工作:

  1. 一个持久信号日志(durable signal log)记录每个会话选定的状态变更。
  2. 监视器(watchers)持有每个目标的游标,并接收一条合并的过期状态通知。
  3. 对账(reconciliation)通过带有 changesSince 的 session_status 拉取精确的变更增量。

信号日志

当被监视的会话发生实质性变化时,OpenClaw 会向共享状态数据库(session_state_events)追加一个带类型的事件。事件携带元数据和一行摘要——绝不会包含消息内容。

类型 记录时机 通知监视器
created 新会话具有可信的创建归属 否(仅记录)
human_direct_message 人类直接向被监视会话发送一个回合 是
upstream_missing 被收养会话的上游来源消失 是
goal_changed 该会话的目标状态被创建、更新或清除 是
child_spawned 子代理或 ACP 子会话被创建 否(播种游标)
run_completed 子运行成功结束 否(仅记录)
run_failed 子运行失败、超时或取消 否(仅记录)
compacted 会话历史被压缩 否(仅记录)
adopted 目录会话被收养到 OpenClaw 中 否(仅记录)

每个事件都会标明其参与者(human、agent 或 system)。被取消或超时的子运行会作为失败记录,并在事件负载中保留精确的结果(cancelled、timeout 或 error)。

会话的状态版本(state version)就是其日志中的最大序列号,记录在持久化的每个会话头部中,该头部在修剪后仍然保留。当会话记录过变更时,sessions_list 行会包含 stateVersion。session_status 始终报告该版本。

仅记录类型的存在是为了对账历史,而非通知:普通的子运行完成投递仍由 子代理公告 负责,信号日志绝不会重复该投递。

会话创建默认还会单独排队一条一次性的 Home 通知,该行为由 session.notifyOnCreate 控制。它不会注册监视器,也不会唤醒 Home。与持久监视器通知不同,它仅使用有界的内存系统事件队列。有关可见性排除项,请参阅 新会话感知。

监视器

监视器是一个对目标持有游标(session_watch_cursors)的会话。游标来自三个来源:

  • 隐式(生成边)。 当会话生成子代理或 ACP 子会话时,父会话的游标会自动以子会话的生成版本为起点播种。父会话从不手动订阅。
  • 环境组。 在 session.groupScope: "per-group" 下,代理的主会话会在其隔离的群组、房间和频道会话出现首次人类回合后监视它们。这与 session.dmScope 无关。将房间路由到主会话不需要监视,因为它已经与主会话共享同一个对话。
  • 显式(sessions_send watch: true)。 具有正常状态可见性的协调器可以监视非生成目标。在 sessions_send 上传递 watch: true。仅凭按代理配置的 tools.agentToAgent.send 规则并不能授予对原本隐藏会话的监视访问权。发送成功投递后,发送方会被注册为实际接收消息会话的监视器。注册从目标的当前状态版本开始——之前的历史绝不会产生通知。当该参数被设置时,工具结果会报告 watched: true|false。

监视器身份必须是代理限定的会话键。在 session.scope="global" 下,共享的 global 键在多个代理之间会产生歧义,因此此类会话会获得持久日志和 changesSince,但不会收到主动通知。

监视还会记录其监视器的物理存储。更改 session.store 不会将其排队的通知转移到另一个具有相同键的会话。具有未知存储来源的旧监视会保留历史,但在主动通知恢复之前需要重新注册。下一次群组回合会在当前存储上注册其环境监视。

监视记录会自我清理:游标行随信号日志保留期过期,在监视器会话重置时被移除,并在任一相关会话被移除时一并移除。已提交的重置即使后续清理步骤失败,仍会清除其监视。v1 中没有取消监视(unwatch)动词。

从会话目录收养的受监视 Claude、Codex、OpenCode 和 Pi 会话会按固定节奏检查是否有直接的上游人类活动。Pi 监视在会话进入其仅追加的 v3 格式后开始。检测到的活动会进入与其他直接人类回合相同的信号日志和监视器流程。

OpenCode 的检测刻意保持保守。OpenCode 的 v1 表不保留消息来源,因此报告不明确的记录会产生误报。逐消息来源仅存在于其 v2 模式中。因此,OpenCode 不会报告仅包含图像的回合、仅包含 @file 提及的回合、路由到子代理的斜杠命令,或来自 ACP 客户端的回合——这些客户端会用受众信息标注内容(OpenCode 将其映射为 synthetic 或 ignored)。它还会抑制与之前 50 条用户消息中任何一条匹配的文本,以捕捉压缩重放。因此,人类如果在该窗口内故意重复相同的文本,可能会被漏掉。

如果已采用会话的上游源被外部删除,连续三次缺失检查会为其观察者产生一个 upstream_missing 信号,并移除上游链接。连续三次检查大约相当于三个监控 tick。再次继续目录会话会创建一个新的链接。

通知:一个,而不是许多

当可通知事件到达,且观察者的游标落后时,观察者会在其下一轮收到一条系统通知:

Session "agent:main:subagent:child" changed (other actor). Reconcile before acting: session_status sessionKey "agent:main:subagent:child" changesSince 12.

主会话观察者也会通过心跳唤醒立即被唤醒。嵌套子代理观察者会在其下一轮收到该通知。

该协议刻意采用反垃圾策略:

  • 每个观察者/目标对只保留一条待处理通知。 待处理期间通知文本保持字节稳定,系统事件队列会基于它去重。对同一目标的二十次快速变更仍只会在观察者提示中产生一行。
  • 冻结水位线。 当通知入队时,游标会冻结其已通知位置。后续实质性事件只会推进实质性水位线。它们不会重新通知。
  • 排空时确认,仅为交错工作重新打开。 当观察者轮次消费通知时,游标会前进。如果在入队和排空之间又有更多实质性事件到达,则只为剩余部分打开一条全新通知。
  • 自我抑制。 观察者永远不会收到其自身引发的事件的通知。
  • 重启恢复。 待处理通知保存在内存队列中。网关重启后,启动扫描会从持久化游标重新物化它们。

协调

通知会告诉观察者确切该做什么。带有 changesSince: <version> 的 session_status 会返回该版本之后的类型化事件(最多 200 个),且不会推进任何游标:

{
  "stateVersion": 19,
  "stateChanges": {
    "events": [
      {
        "sequence": 14,
        "kind": "human_direct_message",
        "actorType": "human",
        "summary": "human message via telegram"
      },
      { "sequence": 19, "kind": "goal_changed", "actorType": "human", "summary": "goal updated" }
    ],
    "historyGap": false
  }
}

historyGap: true 表示请求的版本早于保留的历史——应刷新整个会话状态(sessions_history、session_status),而不是将响应视为精确增量。缺口信号是精确的:它来自每个会话的修剪水位线,而不是从序列算术推断得出。

存储与限制

历史记录保存在共享状态数据库中,限制为 30 天和 50,000 行。修剪后,每个会话的头部保持单调递增。记录是尽力而为的。追加失败会被记录日志,并且永远不会导致源轮次失败。因此,stateVersion 是信号日志头部,而不是事务性变更数据捕获版本。

子运行结果会异步记录,因此等待共享数据库不会阻塞网关事件处理。完成会并入记录工作,被替换或临时运行所有者无法声明该运行的首个终止事件。

记录在等待写入许可后会重新检查会话的所有权。并发的元数据更新或对其他会话的写入不会丢弃一个否则仍然有效的事件。

当前限制:

  • 通知投递假设一个网关进程拥有共享状态数据库。多个网关共享持久化日志和 changesSince,但 v1 不会跨进程推送通知。
  • 压缩事件涵盖嵌入式运行时的压缩所有者。仅原生 harness 的压缩未被完整记录。
  • 取消结果负载详情目前由 ACP 子运行产生。原生子代理取消会表现为通用失败。
  • 上游自回声检测会比较规范化用户文本。外部提示如果匹配该会话最近 10 条 OpenClaw 侧用户消息之一,则被视为自回声。
  • 在 v1 中,单条本地 Claude JSONL 行如果超过每个周期的 1 MiB 扫描上限,会阻塞该会话的游标。未分类字节永远不会被跳过。
  • 在 v1 中,单条 Pi JSONL 行如果超过每个周期的 1 MiB 扫描上限,会阻塞该会话的游标。未分类字节永远不会被跳过。
  • 旧版 Pi 会话被采用时没有上游链接。恢复一次以将文件迁移到 v3,然后再次从目录继续它以开始监控。
  • OpenCode 检查每个周期发出一个批量数据库查询。只有当该查询显示其持久化事件序列已前进时,才会运行会话导出。
  • 配对节点 Claude 检查每个周期分类最新的 50 个转录项。更大的突发可能落在 v1 扫描窗口之外。
  • 配对节点 Claude 历史读取不会暴露明确的线程未找到结果,因此在 v1 中,远程 Claude 删除不会被分类为 upstream_missing。
  • 在 v1 中,未被采用的目录会话仍位于感知层之外。
  • 在此功能之前采用的会话没有上游链接。从目录中继续一次以开始上游监控。
  • 上游监控要求每个已采用的会话键有一个拥有代理。采用会使用已解析的代理并返回代理限定键。不同的被监视键可以监视同一个原生线程。在多个代理 ID 下重用完全相同键的链接会因歧义而被跳过。

本页原文 Markdown:在 AtomGit 查看·内容源自开源项目 cl/openclaw