补充三级上下文校验特性的研究

PR 地址：NousResearch/hermes-agent#47022 · 三级上下文校验 + 多 agent 隔离 + 平台实现

研究摘要

网关里 agent 回复依赖的内部会话状态，可能被竞态条件、队列溢出、ContextVar 泄漏、跨 agent 线程干扰悄悄改坏——状态漂移后 agent 基于错误的上下文给出错误回复。这类 bug 偶发、难复现、破坏信任，且极难定位：表面一切正常，只有回复内容对不上。本研究向 Hermes 上游补充了完整的三级上下文校验系统：发送前校验（Tier 1 pre-send）、FIFO 队列校验（Tier 2）、排空对齐校验（Tier 3），通过平台 API 拉取最近消息与内部状态比对，把"状态漂移"在回复发出前拦截下来；同时为多 agent 场景补上 ContextVar 快照/恢复的线程隔离。实现覆盖 4 个平台（飞书、Telegram、微信、钉钉），附带 7 个新 delegate 隔离测试与完整文档。特性默认关闭，存量用户零影响。

这篇研究拆解三层校验的分工、平台机制差异、多 agent 隔离设计与边界条件。值得说明的是，PR 元数据记录的改动规模（+1631/-60，18 个文件）与 PR body 自述（10 个文件，+1,098/-17）存在口径差异，本文如实并列呈现。

一、问题背景：看不见的状态漂移

1.1 四种漂移来源

网关是典型的并发环境：多个平台消息流、多个会话、多个 agent 线程在同一进程内交错运行。内部会话状态可能被四类因素破坏：

• 竞态条件：并发读写同一状态，时序不对就拿到错值——两个消息流同时更新会话指针，后写者覆盖先写者，上下文跳到错误位置；
• 队列溢出：待处理消息超出单槽容量时，消息被静默丢弃或错位——溢出发生在最忙的时候，而最忙的时候恰恰最需要消息完整；
• ContextVar 泄漏：子线程/子任务未清理上下文变量，把上一个任务的上下文带进下一个——一次委托的残留污染后续所有回复；
• 跨 agent 线程干扰：subagent 线程与主线程共享进程级状态，互相污染——并行委托多个 subagent 时，它们的中间状态在共享空间里打架。

漂移的后果是回复与对话历史对不上——agent 以为自己回复过某句、或引用了错误的上下文，用户看到的是"答非所问"。这类错误单次看只是"一次奇怪的回答"，累积起来却会让用户对 agent 的可靠性产生根本怀疑。

四类来源的共性是“状态与事实脱节”：内部记录与平台真实消息流不一致。校验的本质是周期性重建“状态 ← 事实”的对齐——以平台侧消息为基准修正内部状态，或在无法对齐时拦截回复。

1.2 为什么难排查

漂移类 bug 不报错、不留痕：运行时一切正常，只是结果不对。日志里看不到异常，复现依赖特定时序，单靠人工审查很难定位——代码路径是对的，状态是被外部因素改坏的。排查这类问题需要回答"状态在哪个时刻、被哪条路径改成了什么"，而这正是并发环境里最昂贵的问题。出路是把"内部状态"与"外部事实"（平台侧的真实消息流）在关键节点对齐：平台 API 记录的是不可篡改的事实，内部状态与事实比对，漂移即现形。这正是本特性的核心思路。

二、特性设计：三层校验 + 线程隔离

2.1 三层校验的分工

• Tier 1 发送前校验（pre-send）：回复组装完成、发送之前，通过平台 API 拉取最近的真实消息，与内部会话状态比对，确认上下文一致后才放行发送。这是最后一道闸——拦截发生在错误回复到达用户之前；
• Tier 2 FIFO 队列校验：待处理消息溢出的路径上引入 FIFO 队列（base.py 新增 _pending_queues），保证溢出消息按到达顺序处理，防止消息错位改乱上下文。队列是漂移的高发区，FIFO 语义从结构上消除乱序；
• Tier 3 排空对齐校验（drain alignment）：队列排空时再次对齐内部状态与平台消息序列，收尾阶段兜住前两层遗漏的漂移。三层分别在"发送前、排队中、排空后"三个时机设卡，覆盖状态被篡改的主要窗口。校验行为由配置驱动（gateway/run.py），开启与否、严格与否都可调。

三层设卡的顺序也构成纵深防御：Tier 1 拦在发送前，Tier 2 拦在排队中，Tier 3 拦在排空后——任何一层的遗漏都被下一层兜住，单点失效不会导致整体防护归零。

2.2 平台机制：一个抽象、四种实现

gateway/platforms/base.py 定义 fetch_recent_messages() 抽象方法，各平台按自己的能力实现"拉取最近消息"：

抽象层的价值在于：平台差异被收敛到"怎么拉消息"一个接口上，三层校验逻辑本身与平台无关，新增平台只需实现一个方法。覆盖度差异诚实反映了各平台 API 能力的差距——钉钉只提供单条查询，校验粒度受限，只能确认单条消息的存在性而非完整会话流；未实现的平台走默认空校验，即该校验维度在这些平台上不生效。

平台实现的选择也反映了一个务实原则：校验机制的实现成本与平台 API 能力直接挂钩，宁可先覆盖四个主流平台，也不为所有平台实现同一套而稀释质量；未覆盖平台的防护空缺被如实记录在文档中，留给后续迭代。

2.3 多 agent 与 WebUI 的线程隔离

漂移的另一半来源是线程污染，本特性用 ContextVar 快照/恢复解决：tools/delegate_tool.py 对 subagent 线程在启动时快照、结束时恢复会话上下文，并在结果中携带 _context 元数据，让 subagent 的上下文边界显式化——父 agent 能看到子 agent 使用了什么上下文，隔离状态可审计；gateway/platforms/api_server.py 的 _run_agent worker 线程同样做快照，防止 WebUI 并发请求串上下文——多个浏览器标签同时提问时，每个请求的上下文独立。gateway/session_context.py 提供 snapshot_session_context() / restore_session_context() 两个原语，供各处复用。

快照/恢复方案的作用边界需要明确：ContextVar 捕获的是线程局部上下文，对全局状态（文件、数据库、单例对象）无效；隔离方案解决的是“上下文污染”，而非“共享资源竞争”——后者的并发保护不在本次范围内。配套 7 个 delegate 隔离测试（tests/tools/test_delegate.py）锁定行为，docs/context-verification.md 记录配置示例、平台支持矩阵与多 agent 防护指南。

2.4 配置与兼容性

• context_verification.enabled: false（默认）——全部校验关闭，存量行为零变化；
• strict_mode: false——非严格模式下校验失败仅告警不阻断，回复照常发出；
• timeout: 5——校验操作的超时上限，避免校验本身拖住回复；
• platforms: [feishu, telegram, weixin, dingtalk]——按平台选择启用，未列出的平台不参与校验。

默认关闭 + 非严格模式，是这类防护性系统对兼容性的标准姿态：先让新系统在真实环境中观察行为，确认无误后再逐步收紧。

三、实测结果

PR body 记录的测试状态：

既有测试全量通过 + 新增隔离测试通过，确认校验与隔离改动没有破坏既有行为；预存 heartbeat 测试的偶发失败被如实记录为与本次改动无关的时序敏感问题。三层校验在真实平台消息流上的端到端效果未在 PR body 中记录量化数据，实测部分仅以上述测试状态为准。

测试锚点集中在 delegate 隔离（7 项新测试）；三层校验在四个平台侧的实现缺乏独立的测试覆盖记录，平台实现的正确性依赖既有测试与真实环境验证。

四、能力边界

• 校验依赖平台 API 的可用性与延迟：平台侧限流或不可达时，校验本身可能成为新的失败点（有 5 秒超时兜底，但超时即放弃校验，漂移不被拦截）；
• strict_mode 关闭时，校验失败只告警不阻断，漂移回复仍可能发出，防护强度取决于用户配置；strict_mode 开启时的阻断行为细节未被 PR body 记录；
• 钉钉平台仅支持单条消息查询，校验粒度不足以覆盖完整会话流，误判风险高于完整实现平台；
• Slack、Discord 等平台未实现校验机制，走默认空校验，这些平台上的漂移防护缺失；
• 平台 API 拉取的消息与内部状态天然存在时差，极端竞态下校验可能误判或漏判——校验系统自身也受并发约束；
• PR body 自述改动为 10 个文件 +1,098/-17，与 PR 元数据（18 个文件 +1,631/-60）不一致，本文两处口径均如实记录，差异推测来自提交历史演进，未在 PR body 中解释。
• 校验失败告警的信息量（是否包含差异详情、指向哪个环节）未被记录——告警内容直接决定定位效率，仅提示“上下文不一致”与指出“哪条消息、哪个环节”的排查成本相差很大。

五、PR 信息

• PR 地址：https://github.com/NousResearch/hermes-agent/pull/47022
• 改动规模：元数据 +1,631 / -60，18 个文件；body 自述 10 个文件 +1,098 / -17（口径差异，如实并列）
• 状态：closed
• 提交时间：2026-06-16

本文记录 x7peeps 向 Hermes Agent 上游贡献的特性研究，所有数据来自 PR 实测记录。